| Status | GreenPublished |
|---|---|
| Overview | This page is general awareness, guidance, and recommendations for source code repositories within the NRM |
Repository Type Overview
Repository Type | When to Use | Notes |
|---|---|---|
| Subversion | Never | Subversion is deprecated, do not create any new repositories. |
| BitBucket | Closed, internal | Manual, complex, (currently) in-house. Works with RFC/RFD process and JIRA. Very customizable. |
| Github | Whenever possible | Ideal for automation, open source. Industry leader in most significant areas. Very unconstrained. |
GitHub:
Beginner Guide: https://github.blog/2024-05-27-what-is-git-our-beginners-guide-to-version-control/
- Predominant Source Code Management(SCM) system used in BC Government
- Free code repositories for open source projects
- Free GitHub Actions for open source projects
- Marketplace provides an incredible amount oftechnologies and services
- Free container registry (*within GitHub Actions)
- Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more
- Biggest code repository system
- Highest visibility, globally and locally
- Largest developer ecosystem
- Largest reach for talent
- Largest base for tooling and 3rd party app support
- Functions as a live resume for developers
- System for templating and starting projects quickly
- Content is easily discovered by public search (e.g. Google)
- Open source content is readily available, login-free
- Visibility encourages collaboration and discourages undesirable behavior
- Sensible patterns prevent code from being deployed to production, but not merged
- Versatility allows teams to tailor their processes, increasing productivity
For practices on using GitHub see:
BitBucket:
- JIRA integration
- Connections are stronger between teams and interal processes, e.g. RFC/RFD RFC/RFD
- Fine-grained control, e.g.:
- Prevent even repo administrators from merging code or side-stepping requirements
- Asphyxiate contractors with red tape until code is abandoned and/or overwritten
- Currently on-premise, working Jenkins and minimal firewall/networking changes
- Potential shift to cloud will require similar admin and network changes to GitHub
Subversion (SVN):
- Lessened need to retrain on legacy projects, some are comfortable/familiar
Source Code Repository Naming
- Github: prefix each repository with "nr-"
- e.g. nr-(app-name), replace the (app-name) with actual application/product name.
- e.g. nr-fom-api
Folder Naming
- "frontend" folder for frontend
- for multiple frontends use "frontend-*"
- Example: frontend-admin
- for multiple frontends use "frontend-*"
- "backend" folder for backend
- for multiple backends use "backend-*"
- Example: backend-doc-gen
- for multiple backends use "backend-*"
- "migrations" folder for applications using flyway
- "tests" folder for applications with non-component specific tests (eg. Load). Component specific tests (unit, integration, e2e) should be within their specific subfolder (backend, frontend)
Diagrams
- All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:
- 1x application architecture diagram in the source file format .drawio.xml
- 1x system integration and data flow diagram in the source file format .drawio.xml
- 1x architecture diagram in the file format .png for each .drawio.xml diagram
Source Code Repository Topics
- Topics are labels that create subject-based connections between GitHub repositories and let you explore projects by type, technology, and more
- putting nrs as a topic in the repos.
Mono Repo vs Multi Repo?
As a general recommendation, it is preferred to use product based monorepos.
- TL;DR - mono initially, multi with growth (e.g. +services, micro-service, APIs)
- In a mono repo approach, all services and codebase are kept in a single repository
- Generally speaking, mono repos minimize dependency management
- If you have multiple services sharing the same libraries or common code, you may want to opt for a mono repo architecture
- If you predict that your project will be extremely large or complex, a mono repo approach may become untenable over time
- If you have a large team with multi developers doing commits and triggering builds a mono repo approach may not suit your needs
- If your project is being worked on by multiple teams (e.g. back end & front end teams) you may want to opt for a multi repo architecture
- If a versioning strategy is important to your project and you want to version services independently, a multi repo approach might be a better fit
- If you have more than one team working in multiple repos for your project, developing patterns and best practices within your teams might be important
- Uptime is easier to maintain with a mult-repo approach
- Multi-repo allows for individual parts to be fixed/updated without taking down the service
- Complex projects and supporting architecture (pipelines, APIs, DBs) are easier to manage with multi repo
- Implementation (mono, multi, APIs, auth) matters far more than how the repositories are arranged