diff --git a/confluence/pages/Coding_Patterns_&_Practices/README.md b/confluence/pages/Coding_Patterns_&_Practices/README.md
index b2177e9..2025137 100644
--- a/confluence/pages/Coding_Patterns_&_Practices/README.md
+++ b/confluence/pages/Coding_Patterns_&_Practices/README.md
@@ -1 +1 @@
-| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | 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. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
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
- 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 a pattern (eg. "#<Ticket_number>-Nice Description (#)")
- 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.
\ No newline at end of file
+| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | 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. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
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
- 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 a pattern (eg. "#Ticket Number - Nice Description (#)")
- 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.
\ No newline at end of file
diff --git a/confluence/pages/Coding_Patterns_&_Practices/data.json b/confluence/pages/Coding_Patterns_&_Practices/data.json
index 73e3402..0ac416c 100644
--- a/confluence/pages/Coding_Patterns_&_Practices/data.json
+++ b/confluence/pages/Coding_Patterns_&_Practices/data.json
@@ -1 +1 @@
-{"id":"160074735","type":"page","status":"current","title":"Coding Patterns & Practices","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | 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. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
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
- 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 a pattern (eg. "#<Ticket_number>-Nice Description (#)")
- 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.
","representation":"storage","_expandable":{"content":"/rest/api/content/160074735"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":10},"_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 | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | 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. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
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
- 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 a pattern (eg. "#Ticket Number - Nice Description (#)")
- 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.
","representation":"storage","_expandable":{"content":"/rest/api/content/160074735"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":10},"_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/confluence/pages/Source_Code_Repositories/README.md b/confluence/pages/Source_Code_Repositories/README.md
index ae564ca..ba31d2e 100644
--- a/confluence/pages/Source_Code_Repositories/README.md
+++ b/confluence/pages/Source_Code_Repositories/README.md
@@ -1 +1 @@
-| Status | |
|---|
| Stakeholders | |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Outcome |
|
|---|
| Owner | IITD Architecture |
|---|
Source Code Repository Types
Repository Type | When to Use | Key Contacts | 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:
- Predominant 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
- 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>
- e.g. nr-fom-api
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?
- 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
\ No newline at end of file
+| Status | |
|---|
| Stakeholders | |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Outcome |
|
|---|
| Owner | IITD Architecture |
|---|
Source Code Repository Types
Repository Type | When to Use | Key Contacts | 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:
- Predominant 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
- 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
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?
- 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
\ No newline at end of file
diff --git a/confluence/pages/Source_Code_Repositories/data.json b/confluence/pages/Source_Code_Repositories/data.json
index 66df1c0..86adf0d 100644
--- a/confluence/pages/Source_Code_Repositories/data.json
+++ b/confluence/pages/Source_Code_Repositories/data.json
@@ -1 +1 @@
-{"id":"115081594","type":"page","status":"current","title":"Source Code Repositories","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Outcome |
|
|---|
| Owner | IITD Architecture |
|---|
Source Code Repository Types
Repository Type | When to Use | Key Contacts | 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:
- Predominant 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
- 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>
- e.g. nr-fom-api
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?
- 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":35},"_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 | |
|---|
| Stakeholders | |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Outcome |
|
|---|
| Owner | IITD Architecture |
|---|
Source Code Repository Types
Repository Type | When to Use | Key Contacts | 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:
- Predominant 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
- 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
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?
- 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":35},"_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