,`_ `it makes the tests more readable, predictable and becomes living documentation of the codebase.`
BC Government has published a set of API Guidelines here: [https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines](https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines)
-Information on the corporate API gateway can be found here: [https://bcgov.github.io/aps-infra-platform/](https://bcgov.github.io/aps-infra-platform/)
-
-
+Information on the corporate API gateway can be found here: [https://bcgov.github.io/aps-infra-platform/](https://bcgov.github.io/aps-infra-platform/)
### Database and Data Design
@@ -142,7 +124,7 @@ Most of the teams working on OpenShift are choosing a flavor of PostgreSQL to pe
Some points of consideration are:
-* What type of data are you persisting as part of your application? Are you storing geospatial data? Audio and/or video?
+* What type of data are you persisting as part of your application? Are you storing geospatial data? Audio and/or video?
* What are your preferred integration patterns?
* Do you have any requirements, for example, to replicate data to the BC Geographic Warehouse (BCGW)?
* What are the requirements for consistency, availability and partitioning?
@@ -151,19 +133,19 @@ For NRM guidance specific to data and database design, please visit this space:
Database backups can be setup using the backup container image; information can be found here: [https://developer.gov.bc.ca/Backup-Container](https://developer.gov.bc.ca/Backup-Container)
-**Indigenous Languages:** the BC Government is committed to including [Indigenous languages in government records, systems and services](https://www2.gov.bc.ca/gov/content?id=666A1FD778FA437994E419A98662ED5C). The [BC Sans](https://www2.gov.bc.ca/gov/content/governments/services-for-government/policies-procedures/bc-visual-identity/bc-sans) font is an open-source "living" typeface developed for government to improve the readability and delivery of digital services. It was designed to support special characters and syllabics found in Indigenous Languages in B.C. When designing and building your product, ensure it has the ability to collect, store, manage and display BC Sans characters. Connect with your architects for more details and references.
+**Indigenous Languages:** the BC Government is committed to including [Indigenous languages in government records, systems and services](https://www2.gov.bc.ca/gov/content?id=666A1FD778FA437994E419A98662ED5C). The [BC Sans](https://www2.gov.bc.ca/gov/content/governments/services-for-government/policies-procedures/bc-visual-identity/bc-sans) font is an open-source "living" typeface developed for government to improve the readability and delivery of digital services. It was designed to support special characters and syllabics found in Indigenous Languages in B.C. When designing and building your product, ensure it has the ability to collect, store, manage and display BC Sans characters. Connect with your architects for more details and references.
### Document Storage
-BC Government has an on premise [object storage solution](https://www.dell.com/en-ca/dt/storage/ecs/index.htm#tab0=0&tab1=0) that delivers low cost storage for unstructured and semi-structured data. The service is billed monthly to the highwatermark of the storage your team consumes in their S3 bucket at $0.07/GB/Month. To get an S3 object storage bucket, contact the [Optimize team](https://apps.nrs.gov.bc.ca/int/confluence/display/OPTIMIZE/NRS+Object+Storage).
+BC Government has an on premise [object storage solution](https://www.dell.com/en-ca/dt/storage/ecs/index.htm#tab0=0&tab1=0) that delivers low cost storage for unstructured and semi-structured data. The service is billed monthly to the highwatermark of the storage your team consumes in their S3 bucket at $0.07/GB/Month. To get an S3 object storage bucket, contact the [Optimize team](https://apps.nrs.gov.bc.ca/int/confluence/display/OPTIMIZE/NRS+Object+Storage).
-[COMS (Common Object Management Service)](https://github.com/bcgov/common-object-management-service) is an emerging common component that leverages the object storage solution. The advantage of this component is that it includes the ability to tag and add metadata, and integrates with BC Government's standard identity providers (IDIR, BCeID). To learn more, attend the [Common Services Showcase](https://bcgov.github.io/common-service-showcase/) team sprint reviews or contact the team via email.
+[COMS (Common Object Management Service)](https://github.com/bcgov/common-object-management-service) is an emerging common component that leverages the object storage solution. The advantage of this component is that it includes the ability to tag and add metadata, and integrates with BC Government's standard identity providers (IDIR, BCeID). To learn more, attend the [Common Services Showcase](https://bcgov.github.io/common-service-showcase/) team sprint reviews or contact the team via email.
-An emerging companion to the Common Object Management Service being built by the Common Services team is [BCBox](https://bcbox.nrs.gov.bc.ca), which is a hosted solution that uses the COMS API to allow users to upload, tag and share files using any [OIDC](https://openid.net/connect/) compliant authentication mechanism. The code repository for BCBox can be found [here](https://github.com/bcgov/bcbox).
+An emerging companion to the Common Object Management Service being built by the Common Services team is [BCBox](https://bcbox.nrs.gov.bc.ca), which is a hosted solution that uses the COMS API to allow users to upload, tag and share files using any [OIDC](https://openid.net/connect/) compliant authentication mechanism. The code repository for BCBox can be found [here](https://github.com/bcgov/bcbox).
### Design Guidance
-General resources for Agile designers at Digital Government (BC Visual Identity, Official BC Design System, Web Style Guide, Content Design Guidance, UX Research Guidance, Service Design Playbook) can be found here:
+General resources for Agile designers at Digital Government (BC Visual Identity, Official BC Design System, Web Style Guide, Content Design Guidance, UX Research Guidance, Service Design Playbook) can be found here:
[https://digital.gov.bc.ca/resources#:~:text=Read%20the%20playbook-,For%20Designers,-B.C.%20Visual](https://digital.gov.bc.ca/resources#:~:text=Read%20the%20playbook-,For%20Designers,-B.C.%20Visual)
@@ -175,7 +157,7 @@ BC Parks has extended their Design Guide to include the use of the BC Sans font
### Front End Frameworks
-Many agile teams are using a flavor of Javascript framework for their front end development (Angular, Vue, React etc). We recommend you pick the framework that works best for the team, and **_if you are developing a suite of applications for your program area, harmonize across the suite_** where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
+Many agile teams are using a flavor of Javascript framework for their front end development (Angular, Vue, React etc). We recommend you pick the framework that works best for the team, and **_if you are developing a suite of applications for your program area, harmonize across the suite_** where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
### Web Mapping Frameworks
@@ -183,9 +165,9 @@ A comparison of web mapping frameworks in use in BC Government can found here: [
### Back End Languages
-Similar to front end frameworks, we recommend you choose a development language that best suits the team and the business challenge you are working on. _**If you are developing a suite of applications for your program area, harmonize across the suite**_ where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
+Similar to front end frameworks, we recommend you choose a development language that best suits the team and the business challenge you are working on. _**If you are developing a suite of applications for your program area, harmonize across the suite**_ where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
-There are many languages in use by agile teams across government, the most popular being Go, Python, Java, Javascript and Typescript. The [Technology Radar](https://apps.nrs.gov.bc.ca/int/confluence/display/AR/Technology+Radar) is a great reference to see where the momentum is around languages and frameworks.
+There are many languages in use by agile teams across government, the most popular being Go, Python, Java, Javascript and Typescript. The [Technology Radar](https://apps.nrs.gov.bc.ca/int/confluence/display/AR/Technology+Radar) is a great reference to see where the momentum is around languages and frameworks.
### Web Domains and Certificates
@@ -207,19 +189,19 @@ Digital Government reference: [https://digital.gov.bc.ca/common-components](http
NRM Specific Guidance: [Common Components and Common Services](https://apps.nrs.gov.bc.ca/int/confluence/display/AR/Common+Components+and+Common+Services)
-##### _Community Tip! If you are looking for a common component you think should exist, but doesn't, consider adding some extra design thinking such that other teams can reuse your great work!_
+##### _Community Tip! If you are looking for a common component you think should exist, but doesn't, consider adding some extra design thinking such that other teams can reuse your great work!_
### Reporting and Analytics
-Many teams require reporting and analytics capabilities for their application data. Metabase is an easy-to-use open-source dashboarding and business intelligence tool that has broad usage in the NRM. Architecture has created a packaged install of Metabase tailored to teams wanting secure access to Zone B Oracle databases.
+Many teams require reporting and analytics capabilities for their application data. Metabase is an easy-to-use open-source dashboarding and business intelligence tool that has broad usage in the NRM. Architecture has created a packaged install of Metabase tailored to teams wanting secure access to Zone B Oracle databases.
[https://github.com/bcgov/nr-arch-templates/tree/main/Metabase](https://github.com/bcgov/nr-arch-templates/tree/main/Metabase)
### I need help from the Community!
-There are many teams working across the NRM and beyond. To connect with your NRM colleagues, see the team directory here [NRIDS Development and Digital Services](https://apps.nrs.gov.bc.ca/int/confluence/display/DEVGUILD/NRIDS+Development+and+Digital+Services)
+There are many teams working across the NRM and beyond. To connect with your NRM colleagues, see the team directory here [NRIDS Development and Digital Services](https://apps.nrs.gov.bc.ca/int/confluence/display/DEVGUILD/NRIDS+Development+and+Digital+Services)
-The community uses Rocket.Chat to solicit help from other teams on all sorts of subjects. Users can authenticate with IDIR or their GitHub ID.
+The community uses Rocket.Chat to solicit help from other teams on all sorts of subjects. Users can authenticate with IDIR or their GitHub ID.
[https://chat.developer.gov.bc.ca/](https://chat.developer.gov.bc.ca/)
@@ -243,16 +225,12 @@ BC Gov StackOverflow: [https://stackoverflow.developer.gov.bc.ca/](https://stack
**Q.** Do I need my application and data architecture to be formally approved?
-**A.** No, there is no formal approval process for your architecture. We recommend collaborating with the architecture team during any architectural spikes or any significant architectural decisions. Our collective experience and connectedness across the community can typically provide value for the team.
-
-
+**A.** No, there is no formal approval process for your architecture. We recommend collaborating with the architecture team during any architectural spikes or any significant architectural decisions. Our collective experience and connectedness across the community can typically provide value for the team.
**Q.** Do I have to use OpenShift to host my application?
-**A.** No. We would generally like new applications to be running in a containerized or serverless hosting architecture. OpenShift is a strong option for teams starting out given the maturity of the platform and the surrounding community, as is the AWS Public Cloud Service, both operated by BC Government teams. Following cloud native design principles will help ensure that your application workload is portable between hosting platforms.
-
-
+**A.** No. We would generally like new applications to be running in a containerized or serverless hosting architecture. OpenShift is a strong option for teams starting out given the maturity of the platform and the surrounding community, as is the AWS Public Cloud Service, both operated by BC Government teams. Following cloud native design principles will help ensure that your application workload is portable between hosting platforms.
**Q.** Can I pass my application off to an ops team so the team can work on new apps?
-**A.** We generally follow the "you build it, you run it" philosophy, and therefore recommend you build a sustainment plan into your application roadmap. Adhering as closely as possible to the [12 Factor](https://12factor.net/) principles is a great way to promote a sustainable, cloud native build.
\ No newline at end of file
+**A.** We generally follow the "you build it, you run it" philosophy, and therefore recommend you build a sustainment plan into your application roadmap. Adhering as closely as possible to the [12 Factor](https://12factor.net/) principles is a great way to promote a sustainable, cloud native build.
\ No newline at end of file
diff --git a/patterns/docs/Agile Team Kickstarter/data.json b/patterns/docs/Agile Team Kickstarter/data.json
index 027829f..25826ca 100644
--- a/patterns/docs/Agile Team Kickstarter/data.json
+++ b/patterns/docs/Agile Team Kickstarter/data.json
@@ -1 +1 @@
-{"id":"120392107","type":"page","status":"current","title":"Agile Team Kickstarter","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | The purpose of this page is to outline some of the key information and connections that product teams should be made aware of as part of team inception. This is a living and collaborative document. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
Partnership Agreement
NRM teams that work within our Development and Digital Services (DDS) branch start with a partnership agreement to ensure alignment between NRIDS and the program area.
NRM Digital Service Delivery Partnership Agreement
Team Agreement
Before starting development, or when new team members begin contributing, ensure everyone on the team has the same understanding about coding practices, technology choices, and roles within your team. This is typically done during sprint 0.
Coding Patterns and Practices
Product Lifecycle
Is your team replacing, re-architecting or re-platforming an existing application? If so, it's the Product Owner's responsibility to ensure the existing application is retired and the data is transitioned or preserved to ensure data quality, accuracy and currency as well as overall portfolio sustainability. Product Owners may reach out to their assigned Ministry Portfolio Manager (MPM) for assistance with the Application Retirement process.
Ensure you allocate time and budget in your backlog to manage the overall lifecycle of the business processes, data and associated products.
Helpful links on Application Retirement:
Private Cloud
The BC Government has invested heavily in the Red Hat OpenShift platform to provide self service private cloud capabilities. Training is available through the exchange lab to get teams acquainted with the platform; a good primer is here.
https://developer.gov.bc.ca/ExchangeLab-Course:-OpenShift-101
The landing page for the private cloud service is here: https://cloud.gov.bc.ca/private-cloud/
Namespace provisioning can be found here: https://registry.developer.gov.bc.ca/public-landing
Information on resource tuning for OpenShift Namespaces can be found here: https://beta-docs.developer.gov.bc.ca/application-resource-tuning/
The RedHat learning portal is a great resource to learn more about the platform, and they also provide a sandbox to 'learn by doing'.
Some of the more important concepts to understand up front are:
- Image streams, builds & tagging
- Network policy settings to allow pods to communicate internally and to the web via routes,
- How to get deployments to listen to tags and/or configuration changes (eventually on repo events like pull requests)
- Tuning, health checks, resource allocation and tuning, and pod scaling
OpenShift QuickStart Application
Our friends and collaborators in the Forestry Suite of Applications Modernization Program and Architecture team have created an application template that includes pluggable API backends (Node/Nest, Python/FastAPI, Go/Fiber, Java/Quarkus) and frontend(React, Vite), with a deployment pipeline to the OpenShift platform with an option to include a PostgreSQL/PostGIS database and leveraging the backup container provided by the BC DevExchange. This is a great resource to get product teams up and running.
QuickStart OpenShift
Public Cloud
BC Government has endorsed several public cloud services and provides quickstart guides and sample applications!
https://www2.gov.bc.ca/gov/content/governments/services-for-government/cloud-computing-in-the-bc-government#explore
Approved AWS services can be found here: https://developer.gov.bc.ca/AWS-Services
GitHub
Source code should be stored in a GitHub repository in the "bcgov" tenancy.
Access management for the bcgov GitHub tenancy can be found here: https://just-ask.developer.gov.bc.ca/
NRM specific guidance on Github is here: Source Code Repositories
Authentication and Identity
Most NRM digital products leverage the OCIO SSO service that is backed by Keycloak.
https://bcgov.github.io/sso-requests
https://oidc.gov.bc.ca/auth/
Secrets Management
The platform services team operates a Vault service.
It is described here: https://beta-docs.developer.gov.bc.ca/vault-secrets-management-service/
Access to the service is here: https://vault.developer.gov.bc.ca/ui/vault/auth?with=token
Security and Privacy
It's important that teams engage with the NRM Security and Privacy teams early and often. They can support you with general advice as well as Security Threat Risk Assessments (STRA's) and Privacy Impact Assessments (PIA's).
NRM Security Knowledge Base: NRM Information Security Home
NRM Privacy Knowledge Base: NRM Privacy Knowledge Base
OWASP (Open Web Application Security Project) is another great reference for security best practices for development teams: https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/migrated_content
CI/CD
The deployment pipeline is a key component for your application. For visibility, collaboration and maintainability modern teams are moving away from Jenkins towards GitHub actions.
It is strongly recommended that code be submitted using a Pull Request. Automated testing can and should replace manual UAT wherever practical.
NRM has a modern CI/CD template using GitHub Actions: OpenShift QuickStart . This offering is currently limited OpenShift Silver or Gold Cluster.
Application Programming Interfaces (API's)
We recommend adopting an "API First" philosophy for application development, where teams both build and consume their API's. Providing API specification with proper metadata is mandatory irrespective of the underlying implementation(REST, graphql, grpc etc..)
Along with API first approach the Architecture team highly recommends looking at Domain Driven Design(DDD) where each micro-service API is bounded by its business domain(https://martinfowler.com/bliki/DomainDrivenDesign.html)
Also look at Event-Driven Architecture (Event Sourcing and CQRS) when building micro-services as it promotes highly decoupled APIS, communicating over an event streaming platform (https://microservices.io/patterns/data/event-sourcing.html, https://microservices.io/patterns/data/cqrs.html)
We recommend a Test Driven Development (TDD) approach to API development, as it makes the application code more reliable and efficient along with easier maintenance in the future.
There are several ways to name test methods/functions but we recommend using the pattern test<method_name>_<given_condition>_<expected_behavior>, it makes the tests more readable, predictable and becomes living documentation of the codebase.
BC Government has published a set of API Guidelines here: https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines
Information on the corporate API gateway can be found here: https://bcgov.github.io/aps-infra-platform/
Database and Data Design
Most of the teams working on OpenShift are choosing a flavor of PostgreSQL to persist data for their application.
Some points of consideration are:
- What type of data are you persisting as part of your application? Are you storing geospatial data? Audio and/or video?
- What are your preferred integration patterns?
- Do you have any requirements, for example, to replicate data to the BC Geographic Warehouse (BCGW)?
- What are the requirements for consistency, availability and partitioning?
For NRM guidance specific to data and database design, please visit this space: NRM Data and Database Development Guidelines
Database backups can be setup using the backup container image; information can be found here: https://developer.gov.bc.ca/Backup-Container
Indigenous Languages: the BC Government is committed to including Indigenous languages in government records, systems and services. The BC Sans font is an open-source "living" typeface developed for government to improve the readability and delivery of digital services. It was designed to support special characters and syllabics found in Indigenous Languages in B.C. When designing and building your product, ensure it has the ability to collect, store, manage and display BC Sans characters. Connect with your architects for more details and references.
Document Storage
BC Government has an on premise object storage solution that delivers low cost storage for unstructured and semi-structured data. The service is billed monthly to the highwatermark of the storage your team consumes in their S3 bucket at $0.07/GB/Month. To get an S3 object storage bucket, contact the Optimize team.
COMS (Common Object Management Service) is an emerging common component that leverages the object storage solution. The advantage of this component is that it includes the ability to tag and add metadata, and integrates with BC Government's standard identity providers (IDIR, BCeID). To learn more, attend the Common Services Showcase team sprint reviews or contact the team via email.
An emerging companion to the Common Object Management Service being built by the Common Services team is BCBox, which is a hosted solution that uses the COMS API to allow users to upload, tag and share files using any OIDC compliant authentication mechanism. The code repository for BCBox can be found here.
Design Guidance
General resources for Agile designers at Digital Government (BC Visual Identity, Official BC Design System, Web Style Guide, Content Design Guidance, UX Research Guidance, Service Design Playbook) can be found here:
https://digital.gov.bc.ca/resources#:~:text=Read%20the%20playbook-,For%20Designers,-B.C.%20Visual
Additional design system guidance: https://developer.gov.bc.ca/Design-System/About-the-Design-System
BC Parks has extended their Design Guide to include the use of the BC Sans font and other additions specific to their program:
https://bcgov.github.io/bcparks/design-guides
Front End Frameworks
Many agile teams are using a flavor of Javascript framework for their front end development (Angular, Vue, React etc). We recommend you pick the framework that works best for the team, and if you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
Web Mapping Frameworks
A comparison of web mapping frameworks in use in BC Government can found here: https://bcgov.github.io/bcwebmaps-options/
Back End Languages
Similar to front end frameworks, we recommend you choose a development language that best suits the team and the business challenge you are working on. If you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
There are many languages in use by agile teams across government, the most popular being Go, Python, Java, Javascript and Typescript. The Technology Radar is a great reference to see where the momentum is around languages and frameworks.
Web Domains and Certificates
Information on NRM Web Domains can be found here: Web-Application domains
An example of a public facing URL is https://fom.nrs.gov.bc.ca/public/projects
Information on how to obtain an SSL certificate can be found here: Automation of TLS Certificates for Websites
Further information on security certificates can be found here: Security Certificates
Information on certbot can be found here: https://github.com/BCDevOps/certbot
Common Components
BC Government has a selection of mature common components and common services.
Digital Government reference: https://digital.gov.bc.ca/common-components
NRM Specific Guidance: Common Components and Common Services
Community Tip! If you are looking for a common component you think should exist, but doesn't, consider adding some extra design thinking such that other teams can reuse your great work!
Reporting and Analytics
Many teams require reporting and analytics capabilities for their application data. Metabase is an easy-to-use open-source dashboarding and business intelligence tool that has broad usage in the NRM. Architecture has created a packaged install of Metabase tailored to teams wanting secure access to Zone B Oracle databases.
https://github.com/bcgov/nr-arch-templates/tree/main/Metabase
I need help from the Community!
There are many teams working across the NRM and beyond. To connect with your NRM colleagues, see the team directory here NRIDS Development and Digital Services
The community uses Rocket.Chat to solicit help from other teams on all sorts of subjects. Users can authenticate with IDIR or their GitHub ID.
https://chat.developer.gov.bc.ca/
Channels of interest might include #general #devops-alerts #devops-operations #nr-iitd-agile-teams and any channel prefixed with "#nr-"
The NRM teams have a DevOps Guild to facilitate connections and collaboration between teams: https://apps.nrs.gov.bc.ca/int/confluence/display/DEVGUILD
You can also reach out to the NRM Architecture team, who can help connect your team with the right resources.
Key References:
BC DevHub: https://developer.gov.bc.ca, https://docs.developer.gov.bc.ca/
Common Components: https://digital.gov.bc.ca/common-components
Communities of Practice: https://digital.gov.bc.ca/communities
BC Gov StackOverflow: https://stackoverflow.developer.gov.bc.ca/
FAQ
Q. Do I need my application and data architecture to be formally approved?
A. No, there is no formal approval process for your architecture. We recommend collaborating with the architecture team during any architectural spikes or any significant architectural decisions. Our collective experience and connectedness across the community can typically provide value for the team.
Q. Do I have to use OpenShift to host my application?
A. No. We would generally like new applications to be running in a containerized or serverless hosting architecture. OpenShift is a strong option for teams starting out given the maturity of the platform and the surrounding community, as is the AWS Public Cloud Service, both operated by BC Government teams. Following cloud native design principles will help ensure that your application workload is portable between hosting platforms.
Q. Can I pass my application off to an ops team so the team can work on new apps?
A. We generally follow the "you build it, you run it" philosophy, and therefore recommend you build a sustainment plan into your application roadmap. Adhering as closely as possible to the 12 Factor principles is a great way to promote a sustainable, cloud native build.
","representation":"storage","_expandable":{"content":"/rest/api/content/120392107"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":0},"_links":{"webui":"/display/AR/Agile+Team+Kickstarter","edit":"/pages/resumedraft.action?draftId=120392107","tinyui":"/x/qwktBw","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/120392107"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/120392107/child","restrictions":"/rest/api/content/120392107/restriction/byOperation","history":"/rest/api/content/120392107/history","ancestors":"","version":"","descendants":"/rest/api/content/120392107/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
+{"id":"120392107","type":"page","status":"current","title":"Agile Team Kickstarter","body":{"storage":{"value":"This page has been replicated to a publicly accessible website located here
| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | The purpose of this page is to outline some of the key information and connections that product teams should be made aware of as part of team inception. This is a living and collaborative document. |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
Partnership Agreement
NRM teams that work within our Development and Digital Services (DDS) branch start with a partnership agreement to ensure alignment between NRIDS and the program area.
NRM Digital Service Delivery Partnership Agreement
Team Agreement
Before starting development, or when new team members begin contributing, ensure everyone on the team has the same understanding about coding practices, technology choices, and roles within your team. This is typically done during sprint 0.
Coding Patterns and Practices
Product Lifecycle
Is your team replacing, re-architecting or re-platforming an existing application? If so, it's the Product Owner's responsibility to ensure the existing application is retired and the data is transitioned or preserved to ensure data quality, accuracy and currency as well as overall portfolio sustainability. Product Owners may reach out to their assigned Ministry Portfolio Manager (MPM) for assistance with the Application Retirement process.
Ensure you allocate time and budget in your backlog to manage the overall lifecycle of the business processes, data and associated products.
Helpful links on Application Retirement:
Private Cloud
The BC Government has invested heavily in the Red Hat OpenShift platform to provide self service private cloud capabilities. Training is available through the exchange lab to get teams acquainted with the platform; a good primer is here.
https://developer.gov.bc.ca/ExchangeLab-Course:-OpenShift-101
The landing page for the private cloud service is here: https://cloud.gov.bc.ca/private-cloud/
Namespace provisioning can be found here: https://registry.developer.gov.bc.ca/public-landing
Information on resource tuning for OpenShift Namespaces can be found here: https://beta-docs.developer.gov.bc.ca/application-resource-tuning/
The RedHat learning portal is a great resource to learn more about the platform, and they also provide a sandbox to 'learn by doing'.
Some of the more important concepts to understand up front are:
- Image streams, builds & tagging
- Network policy settings to allow pods to communicate internally and to the web via routes,
- How to get deployments to listen to tags and/or configuration changes (eventually on repo events like pull requests)
- Tuning, health checks, resource allocation and tuning, and pod scaling
OpenShift QuickStart Application
Our friends and collaborators in the Forestry Suite of Applications Modernization Program and Architecture team have created an application template that includes pluggable API backends (Node/Nest, Python/FastAPI, Go/Fiber, Java/Quarkus) and frontend(React, Vite), with a deployment pipeline to the OpenShift platform with an option to include a PostgreSQL/PostGIS database and leveraging the backup container provided by the BC DevExchange. This is a great resource to get product teams up and running.
QuickStart OpenShift
Public Cloud
BC Government has endorsed several public cloud services and provides quickstart guides and sample applications!
https://www2.gov.bc.ca/gov/content/governments/services-for-government/cloud-computing-in-the-bc-government#explore
Approved AWS services can be found here: https://developer.gov.bc.ca/AWS-Services
GitHub
Source code should be stored in a GitHub repository in the "bcgov" tenancy.
Access management for the bcgov GitHub tenancy can be found here: https://just-ask.developer.gov.bc.ca/
NRM specific guidance on Github is here: Source Code Repositories
Authentication and Identity
Most NRM digital products leverage the OCIO SSO service that is backed by Keycloak.
https://bcgov.github.io/sso-requests
https://oidc.gov.bc.ca/auth/
Secrets Management
The platform services team operates a Vault service.
It is described here: https://beta-docs.developer.gov.bc.ca/vault-secrets-management-service/
Access to the service is here: https://vault.developer.gov.bc.ca/ui/vault/auth?with=token
Security and Privacy
It's important that teams engage with the NRM Security and Privacy teams early and often. They can support you with general advice as well as Security Threat Risk Assessments (STRA's) and Privacy Impact Assessments (PIA's).
NRM Security Knowledge Base: NRM Information Security Home
NRM Privacy Knowledge Base: NRM Privacy Knowledge Base
OWASP (Open Web Application Security Project) is another great reference for security best practices for development teams: https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/migrated_content
CI/CD
The deployment pipeline is a key component for your application. For visibility, collaboration and maintainability modern teams are moving away from Jenkins towards GitHub actions.
It is strongly recommended that code be submitted using a Pull Request. Automated testing can and should replace manual UAT wherever practical.
NRM has a modern CI/CD template using GitHub Actions: OpenShift QuickStart . This offering is currently limited OpenShift Silver or Gold Cluster.
Application Programming Interfaces (API's)
We recommend adopting an "API First" philosophy for application development, where teams both build and consume their API's. Providing API specification with proper metadata is mandatory irrespective of the underlying implementation(REST, graphql, grpc etc..)
Along with API first approach the Architecture team highly recommends looking at Domain Driven Design(DDD) where each micro-service API is bounded by its business domain(https://martinfowler.com/bliki/DomainDrivenDesign.html)
Also look at Event-Driven Architecture (Event Sourcing and CQRS) when building micro-services as it promotes highly decoupled APIS, communicating over an event streaming platform (https://microservices.io/patterns/data/event-sourcing.html, https://microservices.io/patterns/data/cqrs.html)
We recommend a Test Driven Development (TDD) approach to API development, as it makes the application code more reliable and efficient along with easier maintenance in the future.
There are several ways to name test methods/functions but we recommend using the pattern test<method_name>_<given_condition>_<expected_behavior>, it makes the tests more readable, predictable and becomes living documentation of the codebase.
BC Government has published a set of API Guidelines here: https://developer.gov.bc.ca/Data-and-APIs/BC-Government-API-Guidelines
Information on the corporate API gateway can be found here: https://bcgov.github.io/aps-infra-platform/
Database and Data Design
Most of the teams working on OpenShift are choosing a flavor of PostgreSQL to persist data for their application.
Some points of consideration are:
- What type of data are you persisting as part of your application? Are you storing geospatial data? Audio and/or video?
- What are your preferred integration patterns?
- Do you have any requirements, for example, to replicate data to the BC Geographic Warehouse (BCGW)?
- What are the requirements for consistency, availability and partitioning?
For NRM guidance specific to data and database design, please visit this space: NRM Data and Database Development Guidelines
Database backups can be setup using the backup container image; information can be found here: https://developer.gov.bc.ca/Backup-Container
Indigenous Languages: the BC Government is committed to including Indigenous languages in government records, systems and services. The BC Sans font is an open-source "living" typeface developed for government to improve the readability and delivery of digital services. It was designed to support special characters and syllabics found in Indigenous Languages in B.C. When designing and building your product, ensure it has the ability to collect, store, manage and display BC Sans characters. Connect with your architects for more details and references.
Document Storage
BC Government has an on premise object storage solution that delivers low cost storage for unstructured and semi-structured data. The service is billed monthly to the highwatermark of the storage your team consumes in their S3 bucket at $0.07/GB/Month. To get an S3 object storage bucket, contact the Optimize team.
COMS (Common Object Management Service) is an emerging common component that leverages the object storage solution. The advantage of this component is that it includes the ability to tag and add metadata, and integrates with BC Government's standard identity providers (IDIR, BCeID). To learn more, attend the Common Services Showcase team sprint reviews or contact the team via email.
An emerging companion to the Common Object Management Service being built by the Common Services team is BCBox, which is a hosted solution that uses the COMS API to allow users to upload, tag and share files using any OIDC compliant authentication mechanism. The code repository for BCBox can be found here.
Design Guidance
General resources for Agile designers at Digital Government (BC Visual Identity, Official BC Design System, Web Style Guide, Content Design Guidance, UX Research Guidance, Service Design Playbook) can be found here:
https://digital.gov.bc.ca/resources#:~:text=Read%20the%20playbook-,For%20Designers,-B.C.%20Visual
Additional design system guidance: https://developer.gov.bc.ca/Design-System/About-the-Design-System
BC Parks has extended their Design Guide to include the use of the BC Sans font and other additions specific to their program:
https://bcgov.github.io/bcparks/design-guides
Front End Frameworks
Many agile teams are using a flavor of Javascript framework for their front end development (Angular, Vue, React etc). We recommend you pick the framework that works best for the team, and if you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
Web Mapping Frameworks
A comparison of web mapping frameworks in use in BC Government can found here: https://bcgov.github.io/bcwebmaps-options/
Back End Languages
Similar to front end frameworks, we recommend you choose a development language that best suits the team and the business challenge you are working on. If you are developing a suite of applications for your program area, harmonize across the suite where that makes sense. This will minimize risk associated with changes to the team and enable other developers to work with your code.
There are many languages in use by agile teams across government, the most popular being Go, Python, Java, Javascript and Typescript. The Technology Radar is a great reference to see where the momentum is around languages and frameworks.
Web Domains and Certificates
Information on NRM Web Domains can be found here: Web-Application domains
An example of a public facing URL is https://fom.nrs.gov.bc.ca/public/projects
Information on how to obtain an SSL certificate can be found here: Automation of TLS Certificates for Websites
Further information on security certificates can be found here: Security Certificates
Information on certbot can be found here: https://github.com/BCDevOps/certbot
Common Components
BC Government has a selection of mature common components and common services.
Digital Government reference: https://digital.gov.bc.ca/common-components
NRM Specific Guidance: Common Components and Common Services
Community Tip! If you are looking for a common component you think should exist, but doesn't, consider adding some extra design thinking such that other teams can reuse your great work!
Reporting and Analytics
Many teams require reporting and analytics capabilities for their application data. Metabase is an easy-to-use open-source dashboarding and business intelligence tool that has broad usage in the NRM. Architecture has created a packaged install of Metabase tailored to teams wanting secure access to Zone B Oracle databases.
https://github.com/bcgov/nr-arch-templates/tree/main/Metabase
I need help from the Community!
There are many teams working across the NRM and beyond. To connect with your NRM colleagues, see the team directory here NRIDS Development and Digital Services
The community uses Rocket.Chat to solicit help from other teams on all sorts of subjects. Users can authenticate with IDIR or their GitHub ID.
https://chat.developer.gov.bc.ca/
Channels of interest might include #general #devops-alerts #devops-operations #nr-iitd-agile-teams and any channel prefixed with "#nr-"
The NRM teams have a DevOps Guild to facilitate connections and collaboration between teams: https://apps.nrs.gov.bc.ca/int/confluence/display/DEVGUILD
You can also reach out to the NRM Architecture team, who can help connect your team with the right resources.
Key References:
BC DevHub: https://developer.gov.bc.ca, https://docs.developer.gov.bc.ca/
Common Components: https://digital.gov.bc.ca/common-components
Communities of Practice: https://digital.gov.bc.ca/communities
BC Gov StackOverflow: https://stackoverflow.developer.gov.bc.ca/
FAQ
Q. Do I need my application and data architecture to be formally approved?
A. No, there is no formal approval process for your architecture. We recommend collaborating with the architecture team during any architectural spikes or any significant architectural decisions. Our collective experience and connectedness across the community can typically provide value for the team.
Q. Do I have to use OpenShift to host my application?
A. No. We would generally like new applications to be running in a containerized or serverless hosting architecture. OpenShift is a strong option for teams starting out given the maturity of the platform and the surrounding community, as is the AWS Public Cloud Service, both operated by BC Government teams. Following cloud native design principles will help ensure that your application workload is portable between hosting platforms.
Q. Can I pass my application off to an ops team so the team can work on new apps?
A. We generally follow the "you build it, you run it" philosophy, and therefore recommend you build a sustainment plan into your application roadmap. Adhering as closely as possible to the 12 Factor principles is a great way to promote a sustainable, cloud native build.
","representation":"storage","_expandable":{"content":"/rest/api/content/120392107"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":0},"_links":{"webui":"/display/AR/Agile+Team+Kickstarter","edit":"/pages/resumedraft.action?draftId=120392107","tinyui":"/x/qwktBw","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/120392107"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/120392107/child","restrictions":"/rest/api/content/120392107/restriction/byOperation","history":"/rest/api/content/120392107/history","ancestors":"","version":"","descendants":"/rest/api/content/120392107/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
diff --git a/patterns/docs/Coding Patterns & Practices/Coding Patterns & Practices.md b/patterns/docs/Coding Patterns & Practices/Coding Patterns & Practices.md
index 2ce0efe..48d0fec 100644
--- a/patterns/docs/Coding Patterns & Practices/Coding Patterns & Practices.md
+++ b/patterns/docs/Coding Patterns & Practices/Coding Patterns & Practices.md
@@ -1,45 +1,21 @@
---
sidebar_position: 4
---
-Status
+| 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) |
|---|
-Document
-
-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**
+### **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**
+### **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.
+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**
+### **Code Design Patterns and Principles**
* Apply SOLID and DRY principles. ([https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english](https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/), [https://www.baeldung.com/cs/dry-software-design-principle](https://www.baeldung.com/cs/dry-software-design-principle))
* Use Composition over inheritance as much as possible.
@@ -51,17 +27,17 @@ Focus on the scale-out vs scale-up as deployments are into containers or serverl
* 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/](https://12factor.net/)
+* Follow The Twelve-Factor App standards -[https://12factor.net/](https://12factor.net/)
* Use testcontainers([https://www.testcontainers.org/](https://www.testcontainers.org/)) or GHA services([https://docs.github.com/en/actions/using-containerized-services/about-service-containers](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**
+### **Folder Structure and Naming Conventions**
* Establish and understand your folder structure, if using a template avoid reorganizing (eg. [https://github.com/bcgov/quickstart-openshift](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)
+* 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.
@@ -77,9 +53,7 @@ Focus on the scale-out vs scale-up as deployments are into containers or serverl
* 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**
+### **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
@@ -97,27 +71,27 @@ The below was created using the [QuickStart OpenShift](https://github.com/bcgov/
trueBranching Strategyfalseautotoptrue10111
-**GitHub PRs - Commits**
+### **GitHub PRs - Commits**
-* Follow the Conventional Commits for a better understanding - [https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/)
+* Follow the Conventional Commits for a better understanding -[https://www.conventionalcommits.org/en/v1.0.0/](https://www.conventionalcommits.org/en/v1.0.0/)
### 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](https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd) or similar (this will help trace a completed task to the code modified)
+* Connect the issue using the button "Connect Issue", if not available install the Chrome Extension[ZenHub for GitHub](https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd)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))
+* Clean up your branches (eg. Delete the branch after the merge is done (after mergingdo not reuse the branch))
-**Dependency Management**
+### **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
+* 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/patterns/docs/Coding Patterns & Practices/data.json b/patterns/docs/Coding Patterns & Practices/data.json
index 0ac416c..0c1a154 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 | |
|---|
| 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/patterns/docs/GitHub Repository Best Practices/GitHub Repository Best Practices.md b/patterns/docs/GitHub Repository Best Practices/GitHub Repository Best Practices.md
index ceb5aac..c7e87b4 100644
--- a/patterns/docs/GitHub Repository Best Practices/GitHub Repository Best Practices.md
+++ b/patterns/docs/GitHub Repository Best Practices/GitHub Repository Best Practices.md
@@ -1,32 +1,14 @@
---
sidebar_position: 3
---
-Status
-
-Document
-
-Stakeholders
-
-NRIDS Architecture, Development & Digital Services, NRM Product Teams
-
-Description
-
-The purpose of this page is to outline practices when using GitHub as your source code repository
-
-Outcome
-
-Consistent point of reference for onboarding new product teams into the NRM's.
-
-Owner
-
-NRIDS (DDS, Architecture)
+| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | The purpose of this page is to outline practices when using GitHub as your source code repository |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
Repository Setup
-================
+----------------
The below options are found under settings
-**Branch Protection**
+### **Branch Protection**
Create at least 1 branch protection rule for your "main" branch that;
@@ -35,7 +17,7 @@ Create at least 1 branch protection rule for your "main" branch that;
Note: Admins can bypass this
-* Enforces status checks to be passed before merging, this should include;
+* Enforces status checks to be passed before merging, this should include;
* SonarCloud (vulnerability, code coverage)
* Code scanning (Trivy, Snyk, CodeQL)
* Builds
@@ -47,17 +29,17 @@ Note: Admins can bypass this
* Ensures branches are up to date before merging
-**Manage Your Administrators**
+### **Manage Your Administrators**
* Have at least 1 backup administrator
* Have as few admins as possible, most developers will not need to be an admin
-**Manage Your Team**
+### **Manage Your Team**
* Create a Team in GitHub and Manage the permission in the team. ([https://github.com/orgs/bcgov/teams](https://github.com/orgs/bcgov/teams))
* This way if the single team is working on multiple products, authorization will be easier to manage and tracking will be easier.
-**Setup Your Pull Request Repository Settings (Very Useful to Help Ensure Guidelines are Followed)**
+### **Setup Your Pull Request Repository Settings (Very Useful to Help Ensure Guidelines are Followed)**
* Use squash merging to keep histories clean
* We recommend using pull request titles
@@ -70,7 +52,7 @@ Note: Admins can bypass this
For additional PR, Pipeline, and Deployment practices: See
-**Create Repository Documentation**
+### **Create Repository Documentation**
* Create a meaningful Readme.md, see [https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/SAMPLE-README.md](https://github.com/bcgov/BC-Policy-Framework-For-GitHub/blob/master/BC-Gov-Org-HowTo/SAMPLE-README.md)
* Add a license and other required documentation, see [https://docs.developer.gov.bc.ca/required-pages-for-github-repository/](https://docs.developer.gov.bc.ca/required-pages-for-github-repository/)
@@ -79,7 +61,7 @@ For additional PR, Pipeline, and Deployment practices: See
* If you're going to use the Wiki make sure you add a reference to it in your Readme.md
* Create a reference in confluence to your repository and documentation
-**GitHub Wiki - Suggestions of What to Add**
+### **GitHub Wiki - Suggestions of What to Add**
* Points of Contact
* How-To's:
@@ -87,9 +69,9 @@ For additional PR, Pipeline, and Deployment practices: See
* Developer Practices
* Coding Practices
* Ticket management
- * Backup and restore
+ * Backup and restore
* Application process flows
-**Handle Your Secrets and Environment Variables**
+### **Handle Your Secrets and Environment Variables**
See
\ No newline at end of file
diff --git a/patterns/docs/GitHub Repository Best Practices/data.json b/patterns/docs/GitHub Repository Best Practices/data.json
index 44e4542..f2b814b 100644
--- a/patterns/docs/GitHub Repository Best Practices/data.json
+++ b/patterns/docs/GitHub Repository Best Practices/data.json
@@ -1 +1 @@
-{"id":"163422029","type":"page","status":"current","title":"GitHub Repository Best Practices","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | The purpose of this page is to outline practices when using GitHub as your source code repository |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
Repository Setup
The below options are found under settings
Branch Protection
Create at least 1 branch protection rule for your "main" branch that;
- Forces an approval before merging to your "main" branch
- An approver should be someone able to understand the code changes and has the authority to approve code changes and pipeline activities associated with a PR Merge (Eg. Data Custodian and Test/Prod deployments)
Note: Admins can bypass this
- Enforces status checks to be passed before merging, this should include;
- SonarCloud (vulnerability, code coverage)
- Code scanning (Trivy, Snyk, CodeQL)
- Builds
- Deployments
- Route verification (up/down, penetration testing)
- Note: checks need to have been run once to populate the drop-down
(Ensure you select your options below when enabling the rule)
- Ensures branches are up to date before merging
Manage Your Administrators
- Have at least 1 backup administrator
- Have as few admins as possible, most developers will not need to be an admin
Manage Your Team
- Create a Team in GitHub and Manage the permission in the team. (https://github.com/orgs/bcgov/teams)
- This way if the single team is working on multiple products, authorization will be easier to manage and tracking will be easier.
Setup Your Pull Request Repository Settings (Very Useful to Help Ensure Guidelines are Followed)
- Use squash merging to keep histories clean
- We recommend using pull request titles
- Suggest updating pull requests
- Being up to date is required (see above)
- Selecting this will add an easy update button to PRs
- Automatically delete head branches, which are merged feature branches
- Excessive numbers of branches can degrade performance and increase clone times
- Long lived-branches are strongly discouraged
For additional PR, Pipeline, and Deployment practices: See
Create Repository Documentation
GitHub Wiki - Suggestions of What to Add
- Points of Contact
- How-To's:
- Running Locally
- Developer Practices
- Coding Practices
- Ticket management
- Backup and restore
- Application process flows
Handle Your Secrets and Environment Variables
See
","representation":"storage","_expandable":{"content":"/rest/api/content/163422029"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":"none"},"_links":{"webui":"/display/AR/GitHub+Repository+Best+Practices","edit":"/pages/resumedraft.action?draftId=163422029","tinyui":"/x/TZ_9CQ","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/163422029"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/163422029/child","restrictions":"/rest/api/content/163422029/restriction/byOperation","history":"/rest/api/content/163422029/history","ancestors":"","version":"","descendants":"/rest/api/content/163422029/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
+{"id":"163422029","type":"page","status":"current","title":"GitHub Repository Best Practices","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | NRIDS Architecture, Development & Digital Services, NRM Product Teams |
|---|
| Description | The purpose of this page is to outline practices when using GitHub as your source code repository |
|---|
| Outcome | Consistent point of reference for onboarding new product teams into the NRM's. |
|---|
| Owner | NRIDS (DDS, Architecture) |
|---|
Repository Setup
The below options are found under settings
Branch Protection
Create at least 1 branch protection rule for your "main" branch that;
- Forces an approval before merging to your "main" branch
- An approver should be someone able to understand the code changes and has the authority to approve code changes and pipeline activities associated with a PR Merge (Eg. Data Custodian and Test/Prod deployments)
Note: Admins can bypass this
- Enforces status checks to be passed before merging, this should include;
- SonarCloud (vulnerability, code coverage)
- Code scanning (Trivy, Snyk, CodeQL)
- Builds
- Deployments
- Route verification (up/down, penetration testing)
- Note: checks need to have been run once to populate the drop-down
(Ensure you select your options below when enabling the rule)
- Ensures branches are up to date before merging
Manage Your Administrators
- Have at least 1 backup administrator
- Have as few admins as possible, most developers will not need to be an admin
Manage Your Team
- Create a Team in GitHub and Manage the permission in the team. (https://github.com/orgs/bcgov/teams)
- This way if the single team is working on multiple products, authorization will be easier to manage and tracking will be easier.
Setup Your Pull Request Repository Settings (Very Useful to Help Ensure Guidelines are Followed)
- Use squash merging to keep histories clean
- We recommend using pull request titles
- Suggest updating pull requests
- Being up to date is required (see above)
- Selecting this will add an easy update button to PRs
- Automatically delete head branches, which are merged feature branches
- Excessive numbers of branches can degrade performance and increase clone times
- Long lived-branches are strongly discouraged
For additional PR, Pipeline, and Deployment practices: See
Create Repository Documentation
GitHub Wiki - Suggestions of What to Add
- Points of Contact
- How-To's:
- Running Locally
- Developer Practices
- Coding Practices
- Ticket management
- Backup and restore
- Application process flows
Handle Your Secrets and Environment Variables
See
","representation":"storage","_expandable":{"content":"/rest/api/content/163422029"}},"_expandable":{"editor":"","view":"","export_view":"","styled_view":"","anonymous_export_view":""}},"extensions":{"position":"none"},"_links":{"webui":"/display/AR/GitHub+Repository+Best+Practices","edit":"/pages/resumedraft.action?draftId=163422029","tinyui":"/x/TZ_9CQ","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/163422029"},"_expandable":{"container":"/rest/api/space/AR","metadata":"","operations":"","children":"/rest/api/content/163422029/child","restrictions":"/rest/api/content/163422029/restriction/byOperation","history":"/rest/api/content/163422029/history","ancestors":"","version":"","descendants":"/rest/api/content/163422029/descendant","space":"/rest/api/space/AR"}}
\ No newline at end of file
diff --git a/patterns/docs/Source Code Repositories/Source Code Repositories.md b/patterns/docs/Source Code Repositories/Source Code Repositories.md
index 501b700..abf81e5 100644
--- a/patterns/docs/Source Code Repositories/Source Code Repositories.md
+++ b/patterns/docs/Source Code Repositories/Source Code Repositories.md
@@ -1,68 +1,43 @@
---
sidebar_position: 2
---
-Status
-
-GreenDocument
-
-Stakeholders
-
-Description
-
-General guidance and recommendations for source code repositories
-
-Outcome
-
-
-
-Owner
-
-IITD Architecture
+| Status | |
|---|
| Stakeholders | NRIDS Architecture |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Owner | NRIDS (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
+When to Use
-
+ |
-Manual, complex, (currently) in-house. Works with RFC/RFD process and JIRA. Very customizable.
+Key Contacts
-Github
+ |
-Whenever possible
+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.
+Ideal for automation, open source. Industry leader in most significant areas. Very unconstrained.
see [https://github.com/bcgov/BC-Policy-Framework-For-GitHub](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](https://github.com/marketplace)
+* Marketplace provides an incredible amount of[technologies and services](https://github.com/marketplace)
* Free container registry (\*within GitHub Actions)
* Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more
* Biggest code repository system
@@ -80,8 +55,6 @@ see [https://github.com/bcgov/BC-Policy-Framework-For-GitHub](https://github.com
For practices on using GitHub see:
-
-
**BitBucket**:
* JIRA integration
@@ -92,8 +65,6 @@ For practices on using GitHub see:
* 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
@@ -106,7 +77,7 @@ For practices on using GitHub see:
### Diagrams
-* All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:
+* 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
diff --git a/patterns/docs/Source Code Repositories/data.json b/patterns/docs/Source Code Repositories/data.json
index 86adf0d..d6440f3 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 | |
|---|
| 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
+{"id":"115081594","type":"page","status":"current","title":"Source Code Repositories","body":{"storage":{"value":"| Status | |
|---|
| Stakeholders | NRIDS Architecture |
|---|
| Description | General guidance and recommendations for source code repositories |
|---|
| Owner | NRIDS (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