diff --git a/patterns/docs/Coding Patterns & Practices/data.json b/patterns/docs/Coding Patterns & Practices/data.json
index c922e6d..8de6773 100644
--- a/patterns/docs/Coding Patterns & Practices/data.json
+++ b/patterns/docs/Coding Patterns & Practices/data.json
@@ -1 +1 @@
-{"id":"160074735","type":"page","status":"current","title":"Coding Patterns & Practices","body":{"storage":{"value":"| Status | |
|---|
| Overview | The purpose of this page is to outline some coding practices when developing an application. Practices used by a team should be documented in the repository. |
|---|
Languages Supported
Currently, most agile teams use one of these 4 languages and it is encouraged to stay within these languages, it may expand in the future. ( Typescript/JavaScript, Java On Native, Python, Go)
Native Deployments
Some Languages are interpreted by their runtime ex:(java on JVM, python, javascript, etc..) whereas some languages are compiled (Golang, Rust).
Use native(static binary) deployments wherever available. for ex: it is a MUST for teams using Java to deploy using GraalVM native image without the overhead of JVM interpreter.
Focus on the scale-out vs scale-up as deployments are into containers or serverless.
Code Design Patterns and Principles
- Apply SOLID and DRY principles. (https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english, https://www.baeldung.com/cs/dry-software-design-principle)
- Use Composition over inheritance as much as possible.
- Use IOC(Inversion of Control) pattern for dependency Injection, following constructor-based injection over setter or field-based injection.
- The Service Layer should contain all the business logic of the application, and wrap each atomic transaction in the proper transaction boundary, Use transactions for read-only methods as well for ex: GET endpoints.
- (controller/endpoints → service → repository/active record → entity/query/mutation)
- The controller should call the service or multiple services inside a transaction boundary to perf
- orm the atomic operation.
- The Service Layer MUST have a transactional context.
- Use Lazy Loading and Cascading in ORM to avoid fetching child entities unnecessarily and also make sure the mutations are cascaded as well.
- Follow the TDD approach and the unit tests become living documentation of code, Stub external services with some sort of code, ex in java :- wiremock or powermock, split test lifecycles, so that UTs and Integration Tests can run independently.
- Follow The Twelve-Factor App standards - https://12factor.net/
- Use testcontainers(https://www.testcontainers.org/) or GHA services(https://docs.github.com/en/actions/using-containerized-services/about-service-containers) for integration TESTS which includes, databases, queues, cache etc...
Folder Structure and Naming Conventions
- Establish and understand your folder structure, if using a template avoid reorganizing (eg. https://github.com/bcgov/quickstart-openshift)
- Have a common consistent way when creating names. (eg. for your controllers - The naming of controller APIs should be in line with the pattern of tag definition in swagger - Swagger Tag resource-subresource - URN resource/subresource/pathParameter/subresource)
Secret and Environment Variable Handling
- Exercise the practice of least privilege (eg. Who can and should be able to access secrets)
- Do not put sensitive information in the code, use a secret
- Use environment variables when they may not be sensitive but change between environments (eg. Dev, Test, Prod)
- Do not create secrets manually in Openshift.
Secure APIs
- APIs should always be secured. This is generally achieved by using role based access based off their role validated via JWT.
- The exception to this would be public APIs.
Error Handling
- Gracefully handle errors
- Use plain language when reporting an error. (example. If an error requires a user to do an action they should be able to follow the direction from the error)
- Avoid generic language (eg. Error, review logs)
Code Formatters and Plugins
- Use common plugins and common formatters across team members to avoid flagging code as changed when it was just the format that was changed. (eg. Prettier, SQL Formatter, ESLint)
- Share the IDE specific formatter in the GitHub to avoid conflicts
Infrastructure as Code
- Keep in mind what happens when things go wrong, and how we recover. Maintain your infrastructure as code where possible. If it's not possible ensure you have sufficient documentation to stand back up your infrastructure.
Pipeline
Align your CI/CD pipeline with your hosting environment (GitHub Actions for Openshift Silver/Gold, GitHub Actions with ArgoCD for Openshift Emerald, GiHub Actions with Terraform for AWS)
- Understand your DevOps pipeline (eg. What happens when I create a PR, merge a PR, how an image gets built, how code get tested)
- Maintain your pipeline and align if possible to common practice (eg. https://github.com/bcgov/quickstart-openshift)
The below was created using the QuickStart OpenShift as a reference. Please refer to the repo for the most up to date information.
trueBranching Strategyfalseautotoptrue10111
GitHub PRs - Commits
PR Review and Practices
- PR titles should follow conventional commit (eg. https://www.conventionalcommits.org/en/v1.0.0/).
- Branches should also follow a similar pattern (eg. feat/$featurename)
- A single PR should be for a single Feature/bug/hotfix/patch/etc and kept as small as possible and reasonable
- Add appropriate labels established by your team. (eg. Adding labels to also indicate the applications being impacted by the PR, for instance, "web" or "API")
- Connect the issue using the button "Connect Issue", if not available install the Chrome Extension ZenHub for GitHub or similar (this will help trace a completed task to the code modified)
- If you are the author of the PR avoid resolving the comments, instead reply to them to let the reviewer be aware of your thoughts.
- If you are a reviewer try to mark the comments as resolved to help the PR author to identify easily what is still missing.
- Comments and conversations on the PR are good to let everyone be aware of what is happening but a quick call can also save a lot of time.
- Once a review is raised, a reviewer should do the best effort to try to find a good moment to start. (eg. in the next 3 business hours. It does not mean finishing it in the 3 hours, just try to start providing some feedback. If multiple PRs are open at the same time the delays will be completely acceptable)
- Review according to best practices for the code and application. PRs are about code review (not people review)
- Have a merging practice. (eg. Squash the commits before merging to keep the main timeline clean)
- Clean up your branches (eg. Delete the branch after the merge is done (after merging do not reuse the branch))
Dependency Management
- It is strongly recommended to keep dependencies updated with automated pull requests from tools like Renovate, Snyk or Dependabot.
- This introduces new features, fix bugs, address vulnerabilities or improve performance, affecting the quality, security, and functionality of a project.
- Regular dependency pull requests help to keep changes small, up to date and, of course, manageable.
- These pull requests should not be closed without careful consideration. Unmerged updates should be written into an issue with reasoning and details to follow up in future.
API framework evaluation factors
The below outlines a few key considerations which would help in the decision-making of language/framework to use for API development for containerized environments.
Details around API Design are outlined here(https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines). The below points are on top of the guidelines provided in the link.
- Developer friendly, community support and libraries.
- Resource Consumption(memory/CPU) the less the better, supports the move towards green computing.
- Automated Open API 3 Specification generation, Swagger UI.
- Automated DB schema management (flyway/Liquibase or something similar).
- ORM integration for Database, ACID, Transaction support, Nested Transactions, Advanced Query with pagination, filter, sorting support.
- Supports TDD(Test Driven Development) out of the box, which supports unit and integration testing.
- Easiness of testing for pipelines and other automation.
- Easiness of OAUTH2 integration.
- Easiness of Circuit breaker integration and Resiliency.
- API versioning.
- Support for REST, GraphQL and gRPC
- Asynchronous REST Client.
- API Health checks(for liveness/readiness checks in Kubernetes world) out of the box which includes checking DB Connections and Message Broker connection (If present).
- Easiness of writing to log files in different formats.
- Switching Between Relational Database should be config only.
- Easy Concurrency.
- Easiness of Integration with Distributed tracing frameworks.
","representation":"storage","_expandable":{"content":"/rest/api/content/160074735"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":9},"_links":{"webui":"/pages/viewpage.action?pageId=160074735","edit":"/pages/resumedraft.action?draftId=160074735","tinyui":"/x/74uKCQ","collection":"/rest/api/content","base":"https://apps.nrs.gov.bc.ca/int/confluence","context":"/int/confluence","self":"https://apps.nrs.gov.bc.ca/int/confluence/rest/api/content/160074735"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/160074735/child","restrictions":"/rest/api/content/160074735/restriction/byOperation","history":"/rest/api/content/160074735/history","ancestors":"","version":"","descendants":"/rest/api/content/160074735/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
+{"id":"160074735","type":"page","status":"current","title":"Coding Patterns & Practices","body":{"storage":{"value":"| Status | |
|---|
| Overview | The purpose of this page is to outline some coding practices when developing an application. Practices used by a team should be documented in the repository. |
|---|
Languages Supported
Currently, most agile teams use one of these 4 languages and it is encouraged to stay within these languages, it may expand in the future. ( Typescript/JavaScript, Java On Native, Python, Go)
Native Deployments
Some Languages are interpreted by their runtime ex:(java on JVM, python, javascript, etc..) whereas some languages are compiled (Golang, Rust).
Use native(static binary) deployments wherever available. for ex: it is a MUST for teams using Java to deploy using GraalVM native image without the overhead of JVM interpreter.
Focus on the scale-out vs scale-up as deployments are into containers or serverless.
Code Design Patterns and Principles
- Apply SOLID and DRY principles. (https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english, https://www.baeldung.com/cs/dry-software-design-principle)
- Use Composition over inheritance as much as possible.
- Use IOC(Inversion of Control) pattern for dependency Injection, following constructor-based injection over setter or field-based injection.
- The Service Layer should contain all the business logic of the application, and wrap each atomic transaction in the proper transaction boundary, Use transactions for read-only methods as well for ex: GET endpoints.
- (controller/endpoints → service → repository/active record → entity/query/mutation)
- The controller should call the service or multiple services inside a transaction boundary to perf
- orm the atomic operation.
- The Service Layer MUST have a transactional context.
- Use Lazy Loading and Cascading in ORM to avoid fetching child entities unnecessarily and also make sure the mutations are cascaded as well.
- Follow the TDD approach and the unit tests become living documentation of code, Stub external services with some sort of code, ex in java :- wiremock or powermock, split test lifecycles, so that UTs and Integration Tests can run independently.
- Follow The Twelve-Factor App standards - https://12factor.net/
- Use testcontainers(https://www.testcontainers.org/) or GHA services(https://docs.github.com/en/actions/using-containerized-services/about-service-containers) for integration TESTS which includes, databases, queues, cache etc...
Folder Structure and Naming Conventions
- Establish and understand your folder structure, if using a template avoid reorganizing (eg. https://github.com/bcgov/quickstart-openshift)
- Have a common consistent way when creating names. (eg. for your controllers - The naming of controller APIs should be in line with the pattern of tag definition in swagger - Swagger Tag resource-subresource - URN resource/subresource/pathParameter/subresource)
Secret and Environment Variable Handling
- Exercise the practice of least privilege (eg. Who can and should be able to access secrets)
- Do not put sensitive information in the code, use a secret
- Use environment variables when they may not be sensitive but change between environments (eg. Dev, Test, Prod)
- Do not create secrets manually in Openshift.
Secure APIs
- APIs should always be secured. This is generally achieved by using role based access based off their role validated via JWT.
- The exception to this would be public APIs.
Error Handling
- Gracefully handle errors
- Use plain language when reporting an error. (example. If an error requires a user to do an action they should be able to follow the direction from the error)
- Avoid generic language (eg. Error, review logs)
Code Formatters and Plugins
- Use common plugins and common formatters across team members to avoid flagging code as changed when it was just the format that was changed. (eg. Prettier, SQL Formatter, ESLint)
- Share the IDE specific formatter in the GitHub to avoid conflicts
Infrastructure as Code
- Keep in mind what happens when things go wrong, and how we recover. Maintain your infrastructure as code where possible. If it's not possible ensure you have sufficient documentation to stand back up your infrastructure.
Pipeline
Align your CI/CD pipeline with your hosting environment (GitHub Actions for Openshift Silver/Gold, GitHub Actions with ArgoCD for Openshift Emerald, GiHub Actions with Terraform for AWS)
- Understand your DevOps pipeline (eg. What happens when I create a PR, merge a PR, how an image gets built, how code get tested)
- Maintain your pipeline and align if possible to common practice (eg. https://github.com/bcgov/quickstart-openshift)
The below was created using the QuickStart OpenShift as a reference. Please refer to the repo for the most up to date information.
trueBranching Strategyfalseautotoptrue10111
GitHub PRs - Commits
PR Review and Practices
- PR titles should follow conventional commit (eg. https://www.conventionalcommits.org/en/v1.0.0/).
- Branches should also follow a similar pattern (eg. feat/$featurename)
- A single PR should be for a single Feature/bug/hotfix/patch/etc and kept as small as possible and reasonable
- Add appropriate labels established by your team. (eg. Adding labels to also indicate the applications being impacted by the PR, for instance, "web" or "API")
- Connect the issue using the button "Connect Issue", if not available install the Chrome Extension ZenHub for GitHub or similar (this will help trace a completed task to the code modified)
- If you are the author of the PR avoid resolving the comments, instead reply to them to let the reviewer be aware of your thoughts.
- If you are a reviewer try to mark the comments as resolved to help the PR author to identify easily what is still missing.
- Comments and conversations on the PR are good to let everyone be aware of what is happening but a quick call can also save a lot of time.
- Once a review is raised, a reviewer should do the best effort to try to find a good moment to start. (eg. in the next 3 business hours. It does not mean finishing it in the 3 hours, just try to start providing some feedback. If multiple PRs are open at the same time the delays will be completely acceptable)
- Review according to best practices for the code and application. PRs are about code review (not people review)
- Have a merging practice. (eg. Squash the commits before merging to keep the main timeline clean)
- Clean up your branches (eg. Delete the branch after the merge is done (after merging do not reuse the branch))
Dependency Management
- It is strongly recommended to keep dependencies updated with automated pull requests from tools like Renovate, Snyk or Dependabot.
- This introduces new features, fix bugs, address vulnerabilities or improve performance, affecting the quality, security, and functionality of a project.
- Regular dependency pull requests help to keep changes small, up to date and, of course, manageable.
- These pull requests should not be closed without careful consideration. Unmerged updates should be written into an issue with reasoning and details to follow up in future.
API framework evaluation factors
The below outlines a few key considerations which would help in the decision-making of language/framework to use for API development for containerized environments.
Details around API Design are outlined here(https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines). The below points are on top of the guidelines provided in the link.
- Developer friendly, community support and libraries.
- Resource Consumption(memory/CPU) the less the better, supports the move towards green computing.
- Automated Open API 3 Specification generation, Swagger UI.
- Automated DB schema management (flyway/Liquibase or something similar).
- ORM integration for Database, ACID, Transaction support, Nested Transactions, Advanced Query with pagination, filter, sorting support.
- Supports TDD(Test Driven Development) out of the box, which supports unit and integration testing.
- Easiness of testing for pipelines and other automation.
- Easiness of OAUTH2 integration.
- Easiness of Circuit breaker integration and Resiliency.
- API versioning.
- Support for REST, GraphQL and gRPC
- Asynchronous REST Client.
- API Health checks(for liveness/readiness checks in Kubernetes world) out of the box which includes checking DB Connections and Message Broker connection (If present).
- Easiness of writing to log files in different formats.
- Switching Between Relational Database should be config only.
- Easy Concurrency.
- Easiness of Integration with Distributed tracing frameworks.
","representation":"storage","_expandable":{"content":"/rest/api/content/160074735"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":8},"_links":{"webui":"/pages/viewpage.action?pageId=160074735","edit":"/pages/resumedraft.action?draftId=160074735","tinyui":"/x/74uKCQ","collection":"/rest/api/content","base":"https://apps.nrs.gov.bc.ca/int/confluence","context":"/int/confluence","self":"https://apps.nrs.gov.bc.ca/int/confluence/rest/api/content/160074735"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/160074735/child","restrictions":"/rest/api/content/160074735/restriction/byOperation","history":"/rest/api/content/160074735/history","ancestors":"","version":"","descendants":"/rest/api/content/160074735/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
diff --git a/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/Java Over Oracle On-Prem JDK And Dependency version recommendations.md b/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/Java Over Oracle On-Prem JDK And Dependency version recommendations.md
new file mode 100644
index 0000000..3f7b8a3
--- /dev/null
+++ b/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/Java Over Oracle On-Prem JDK And Dependency version recommendations.md
@@ -0,0 +1,6 @@
+---
+sidebar_position: 1
+---
+This page outlines the recommended versions of heavily used web frameworks / ORMs, each application dependencies needs to be analyzed separately for upgrades.
+
+
\ No newline at end of file
diff --git a/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/data.json b/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/data.json
new file mode 100644
index 0000000..f310f09
--- /dev/null
+++ b/patterns/docs/Source Code Repositories/Java Over Oracle On-Prem JDK And Dependency version recommendations/data.json
@@ -0,0 +1 @@
+{"id":"211816995","type":"page","status":"current","title":"Java Over Oracle On-Prem JDK And Dependency version recommendations","body":{"storage":{"value":"This page outlines the recommended versions of heavily used web frameworks / ORMs, each application dependencies needs to be analyzed separately for upgrades.
","representation":"storage","_expandable":{"content":"/rest/api/content/211816995"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":"none"},"_links":{"webui":"/display/AR/Java+Over+Oracle+On-Prem+JDK+And+Dependency+version+recommendations","edit":"/pages/resumedraft.action?draftId=211816995","tinyui":"/x/IxKgD","self":"https://apps.nrs.gov.bc.ca/int/confluence/rest/api/content/211816995"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/211816995/child","restrictions":"/rest/api/content/211816995/restriction/byOperation","history":"/rest/api/content/211816995/history","ancestors":"","version":"","descendants":"/rest/api/content/211816995/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
diff --git a/patterns/docs/Source Code Repositories/data.json b/patterns/docs/Source Code Repositories/data.json
index 5f57685..673b7ad 100644
--- a/patterns/docs/Source Code Repositories/data.json
+++ b/patterns/docs/Source Code Repositories/data.json
@@ -1 +1 @@
-{"id":"115081594","type":"page","status":"current","title":"Source Code Repositories","body":{"storage":{"value":"| Status | |
|---|
| Overview | This page is general awareness, guidance, and recommendations for source code repositories within the NRM |
|---|
Repository Type Overview
Repository Type | When to Use | Notes |
|---|
| Subversion | Never | Subversion is deprecated, do not create any new repositories. |
| BitBucket | Closed, internal | Manual, complex, (currently) in-house. Works with RFC/RFD process and JIRA. Very customizable. |
| Github | Whenever possible | Ideal for automation, open source. Industry leader in most significant areas. Very unconstrained. see https://github.com/bcgov/BC-Policy-Framework-For-GitHub |
GitHub:
Beginner Guide: https://github.blog/2024-05-27-what-is-git-our-beginners-guide-to-version-control/
- Predominant Source Code Management(SCM) system used in BC Government
- Free code repositories for open source projects
- Free GitHub Actions for open source projects
- Marketplace provides an incredible amount of technologies and services
- Free container registry (*within GitHub Actions)
- Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more
- Biggest code repository system
- Highest visibility, globally and locally
- Largest developer ecosystem
- Largest reach for talent
- Largest base for tooling and 3rd party app support
- Functions as a live resume for developers
- System for templating and starting projects quickly
- Content is easily discovered by public search (e.g. Google)
- Open source content is readily available, login-free
- Visibility encourages collaboration and discourages undesirable behavior
- Sensible patterns prevent code from being deployed to production, but not merged
- Versatility allows teams to tailor their processes, increasing productivity
For practices on using GitHub see:
BitBucket:
- JIRA integration
- Connections are stronger between teams and interal processes, e.g. RFC/RFD RFC/RFD
- Fine-grained control, e.g.:
- Prevent even repo administrators from merging code or side-stepping requirements
- Asphyxiate contractors with red tape until code is abandoned and/or overwritten
- Currently on-premise, working Jenkins and minimal firewall/networking changes
- Potential shift to cloud will require similar admin and network changes to GitHub
Subversion (SVN):
- Lessened need to retrain on legacy projects, some are comfortable/familiar
Source Code Repository Naming
- Github: prefix each repository with "nr-"
- e.g. nr-(app-name), replace the (app-name) with actual application/product name.
- e.g. nr-fom-api
Folder Naming
- "frontend" folder for frontend
- for multiple frontends use "frontend-*"
- "backend" folder for backend
- for multiple backends use "backend-*"
- "migrations" folder for applications using flyway
- "tests" folder for applications with non-component specific tests (eg. Load). Component specific tests (unit, integration, e2e) should be within their specific subfolder (backend, frontend)
Diagrams
- All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:
- 1x application architecture diagram in the source file format .drawio.xml
- 1x system integration and data flow diagram in the source file format .drawio.xml
- 1x architecture diagram in the file format .png for each .drawio.xml diagram
Source Code Repository Topics
- Topics are labels that create subject-based connections between GitHub repositories and let you explore projects by type, technology, and more
- putting nrs as a topic in the repos.
Mono Repo vs Multi Repo?
As a general recommendation, it is preferred to use product based monorepos.
- TL;DR - mono initially, multi with growth (e.g. +services, micro-service, APIs)
- In a mono repo approach, all services and codebase are kept in a single repository
- Generally speaking, mono repos minimize dependency management
- If you have multiple services sharing the same libraries or common code, you may want to opt for a mono repo architecture
- If you predict that your project will be extremely large or complex, a mono repo approach may become untenable over time
- If you have a large team with multi developers doing commits and triggering builds a mono repo approach may not suit your needs
- If your project is being worked on by multiple teams (e.g. back end & front end teams) you may want to opt for a multi repo architecture
- If a versioning strategy is important to your project and you want to version services independently, a multi repo approach might be a better fit
- If you have more than one team working in multiple repos for your project, developing patterns and best practices within your teams might be important
- Uptime is easier to maintain with a mult-repo approach
- Multi-repo allows for individual parts to be fixed/updated without taking down the service
- Complex projects and supporting architecture (pipelines, APIs, DBs) are easier to manage with multi repo
- Implementation (mono, multi, APIs, auth) matters far more than how the repositories are arranged
Source Code Repository License & Ownership
","representation":"storage","_expandable":{"content":"/rest/api/content/115081594"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":34},"_links":{"webui":"/display/AR/Source+Code+Repositories","edit":"/pages/resumedraft.action?draftId=115081594","tinyui":"/x/egHcBg","collection":"/rest/api/content","base":"https://apps.nrs.gov.bc.ca/int/confluence","context":"/int/confluence","self":"https://apps.nrs.gov.bc.ca/int/confluence/rest/api/content/115081594"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/115081594/child","restrictions":"/rest/api/content/115081594/restriction/byOperation","history":"/rest/api/content/115081594/history","ancestors":"","version":"","descendants":"/rest/api/content/115081594/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
+{"id":"115081594","type":"page","status":"current","title":"Source Code Repositories","body":{"storage":{"value":"| Status | |
|---|
| Overview | This page is general awareness, guidance, and recommendations for source code repositories within the NRM |
|---|
Repository Type Overview
Repository Type | When to Use | Notes |
|---|
| Subversion | Never | Subversion is deprecated, do not create any new repositories. |
| BitBucket | Closed, internal | Manual, complex, (currently) in-house. Works with RFC/RFD process and JIRA. Very customizable. |
| Github | Whenever possible | Ideal for automation, open source. Industry leader in most significant areas. Very unconstrained. see https://github.com/bcgov/BC-Policy-Framework-For-GitHub |
GitHub:
Beginner Guide: https://github.blog/2024-05-27-what-is-git-our-beginners-guide-to-version-control/
- Predominant Source Code Management(SCM) system used in BC Government
- Free code repositories for open source projects
- Free GitHub Actions for open source projects
- Marketplace provides an incredible amount of technologies and services
- Free container registry (*within GitHub Actions)
- Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more
- Biggest code repository system
- Highest visibility, globally and locally
- Largest developer ecosystem
- Largest reach for talent
- Largest base for tooling and 3rd party app support
- Functions as a live resume for developers
- System for templating and starting projects quickly
- Content is easily discovered by public search (e.g. Google)
- Open source content is readily available, login-free
- Visibility encourages collaboration and discourages undesirable behavior
- Sensible patterns prevent code from being deployed to production, but not merged
- Versatility allows teams to tailor their processes, increasing productivity
For practices on using GitHub see:
BitBucket:
- JIRA integration
- Connections are stronger between teams and interal processes, e.g. RFC/RFD RFC/RFD
- Fine-grained control, e.g.:
- Prevent even repo administrators from merging code or side-stepping requirements
- Asphyxiate contractors with red tape until code is abandoned and/or overwritten
- Currently on-premise, working Jenkins and minimal firewall/networking changes
- Potential shift to cloud will require similar admin and network changes to GitHub
Subversion (SVN):
- Lessened need to retrain on legacy projects, some are comfortable/familiar
Source Code Repository Naming
- Github: prefix each repository with "nr-"
- e.g. nr-(app-name), replace the (app-name) with actual application/product name.
- e.g. nr-fom-api
Folder Naming
- "frontend" folder for frontend
- for multiple frontends use "frontend-*"
- "backend" folder for backend
- for multiple backends use "backend-*"
- "migrations" folder for applications using flyway
- "tests" folder for applications with non-component specific tests (eg. Load). Component specific tests (unit, integration, e2e) should be within their specific subfolder (backend, frontend)
Diagrams
- All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:
- 1x application architecture diagram in the source file format .drawio.xml
- 1x system integration and data flow diagram in the source file format .drawio.xml
- 1x architecture diagram in the file format .png for each .drawio.xml diagram
Source Code Repository Topics
- Topics are labels that create subject-based connections between GitHub repositories and let you explore projects by type, technology, and more
- putting nrs as a topic in the repos.
Mono Repo vs Multi Repo?
As a general recommendation, it is preferred to use product based monorepos.
- TL;DR - mono initially, multi with growth (e.g. +services, micro-service, APIs)
- In a mono repo approach, all services and codebase are kept in a single repository
- Generally speaking, mono repos minimize dependency management
- If you have multiple services sharing the same libraries or common code, you may want to opt for a mono repo architecture
- If you predict that your project will be extremely large or complex, a mono repo approach may become untenable over time
- If you have a large team with multi developers doing commits and triggering builds a mono repo approach may not suit your needs
- If your project is being worked on by multiple teams (e.g. back end & front end teams) you may want to opt for a multi repo architecture
- If a versioning strategy is important to your project and you want to version services independently, a multi repo approach might be a better fit
- If you have more than one team working in multiple repos for your project, developing patterns and best practices within your teams might be important
- Uptime is easier to maintain with a mult-repo approach
- Multi-repo allows for individual parts to be fixed/updated without taking down the service
- Complex projects and supporting architecture (pipelines, APIs, DBs) are easier to manage with multi repo
- Implementation (mono, multi, APIs, auth) matters far more than how the repositories are arranged
Source Code Repository License & Ownership
","representation":"storage","_expandable":{"content":"/rest/api/content/115081594"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":30},"_links":{"webui":"/display/AR/Source+Code+Repositories","edit":"/pages/resumedraft.action?draftId=115081594","tinyui":"/x/egHcBg","collection":"/rest/api/content","base":"https://apps.nrs.gov.bc.ca/int/confluence","context":"/int/confluence","self":"https://apps.nrs.gov.bc.ca/int/confluence/rest/api/content/115081594"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/115081594/child","restrictions":"/rest/api/content/115081594/restriction/byOperation","history":"/rest/api/content/115081594/history","ancestors":"","version":"","descendants":"/rest/api/content/115081594/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file