Adding or updating the confluence pages

confluence/pages/Source_Code_Repositories/README.md

@@ -1 +1 @@
-<ac:structured-macro ac:name="details" ac:schema-version="1" ac:macro-id="5f5c56f3-5d6c-46cf-ad8f-f3ff3d2ece6b"><ac:parameter ac:name="label" /><ac:rich-text-body><table class="wrapped"><colgroup><col /><col /></colgroup><tbody><tr><th>Status</th><td><div class="content-wrapper"><p><ac:structured-macro ac:name="status" ac:schema-version="1" ac:macro-id="ddabb8ed-6687-4038-9868-5cdb89b54afd"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">Document</ac:parameter></ac:structured-macro></p></div></td></tr><tr><th>Stakeholders</th><td><div class="content-wrapper"><p><ac:link><ri:user ri:userkey="0ea233ad7d54d280017d9b830b4f0008" /></ac:link> <ac:link><ri:user ri:userkey="0ea2648d4daa8a64014dbb62f12c0008" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a47638a3dd01776904055a002b" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a46ee6708d017011b1fa350019" /></ac:link> <ac:link><ri:user ri:userkey="0ea2648d4dfcf8d0014ed0ce7d8b0016" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a467b803370167d33966e10002" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a463ea71d2016485f6bd890006" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a46d11a926016d3b1bc2330006" /></ac:link>  </p></div></td></tr><tr><th>Description</th><td>General guidance and recommendations for source code repositories</td></tr><tr><th>Outcome</th><td><br /></td></tr><tr><th>Owner</th><td>IITD Architecture</td></tr></tbody></table></ac:rich-text-body></ac:structured-macro><h3 style="text-align: left;">Source Code Repository Types</h3><table class="wrapped"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th style="text-align: left;"><p>Repository Type</p></th><th style="text-align: left;"><p>When to Use</p></th><th style="text-align: left;"><p>Key Contacts</p></th><th style="text-align: left;"><p>Notes</p></th></tr></thead><tbody><tr><td style="text-align: left;">Subversion</td><td style="text-align: left;">Never</td><td style="text-align: left;"><br /></td><td style="text-align: left;">Subversion is deprecated, do not create any new repositories.</td></tr><tr><td style="text-align: left;">BitBucket</td><td style="text-align: left;">Closed, internal</td><td style="text-align: left;"><br /></td><td style="text-align: left;">Manual, complex, (currently) in-house.  Works with RFC/RFD process and JIRA.  Very customizable.</td></tr><tr><td style="text-align: left;">Github</td><td style="text-align: left;">Whenever possible</td><td style="text-align: left;"><br /></td><td style="text-align: left;"><p>Ideal for automation, open source.  Industry leader in most significant areas.  Very unconstrained. </p><p>see <a href="https://github.com/bcgov/BC-Policy-Framework-For-GitHub">https://github.com/bcgov/BC-Policy-Framework-For-GitHub</a></p></td></tr></tbody></table><p style="text-align: left;"><br /></p><p style="text-align: left;"><strong>GitHub</strong>:</p><ul style="text-align: left;"><li>Predominant SCM system used in BC Government</li><li>Free code repositories for open source projects</li><li>Free GitHub Actions for open source projects</li><li>Marketplace provides an incredible amount of<span> </span><a href="https://github.com/marketplace" class="external-link" rel="nofollow">technologies and services</a></li><li>Free container registry (*within GitHub Actions)<ul><li>Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more</li></ul></li><li>Biggest code repository system<ul><li>Highest visibility, globally and locally</li><li>Largest developer ecosystem</li><li>Largest reach for talent</li><li>Largest base for tooling and 3rd party app support</li></ul></li><li>Functions as a live resume for developers</li><li><span>System for templating and <a href="https://github.com/bcgov/greenfield-template">starting projects quickly</a></span></li><li><span>Content is easily discovered by public search (e.g. Google)</span></li><li><span>Open source content is readily available, login-free</span></li><li><span>Visibility encourages collaboration and discourages undesirable behavior</span></li><li><span>Sensible patterns prevent code from being deployed to production, but not merged</span></li><li><span>Versatility allows teams to tailor their processes, increasing productivity</span></li></ul><p><span>For practices on using GitHub see: <ac:link><ri:page ri:content-title="GitHub Repository Best Practices" /></ac:link></span></p><p><br /></p><p><span><strong>BitBucket</strong>:</span></p><ul style="list-style-type: square;"><li>JIRA integration</li><li>Connections are stronger between teams and interal processes, e.g. RFC/RFD</li><li>Fine-grained control, e.g.:<ul style="list-style-type: square;"><li>Prevent even repo administrators from merging code or side-stepping requirements</li><li>Asphyxiate contractors with red tape until code is abandoned and/or overwritten</li></ul></li><li>Currently on-premise, working Jenkins and minimal firewall/networking changes</li><li>Potential shift to cloud will require similar admin and network changes to GitHub</li></ul><p><br /></p><p><strong>Subversion (SVN)</strong>:</p><ul style="list-style-type: square;"><li>Lessened need to retrain on legacy projects, some are comfortable/familiar</li></ul><h3>Source Code Repository Naming</h3><ul><li>Github: prefix each repository with &quot;nr-&quot;<ul><li>e.g. nr-&lt;app-name&gt;</li><li>e.g. nr-fom-api</li></ul></li></ul><h3>Diagrams</h3><ul><li>All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:<br /><ul><li>1x application architecture diagram in the source file format .drawio.xml</li><li>1x system integration and data flow diagram in the source file format .drawio.xml</li><li>1x architecture diagram in the file format .png for each .drawio.xml diagram</li></ul></li></ul><h3>Source Code Repository Topics</h3><ul><li><span class="ILfuVd"><span class="hgKElc">Topics are labels that create subject-based connections between GitHub repositories and let you explore projects by type, technology, and more</span></span></li><li><span class="ILfuVd"><span class="hgKElc">putting nrs as a topic in the repos.</span></span></li></ul><h3>Mono Repo vs Multi Repo?</h3><ul><li><span class="hs_cos_wrapper hs_cos_wrapper_meta_field hs_cos_wrapper_type_rich_text">TL;DR - mono initially, multi with growth (e.g. +services, micro-service, APIs)</span></li><li><span class="hs_cos_wrapper hs_cos_wrapper_meta_field hs_cos_wrapper_type_rich_text">In a mono repo approach, all services and codebase are kept in a single repository</span></li><li>Generally speaking, mono repos minimize dependency management</li><li>If you have multiple services sharing the same libraries or common code, you may want to opt for a mono repo architecture</li><li>If you predict that your project will be extremely large or complex, a mono repo approach may become untenable over time</li><li>If you have a large team with multi developers doing commits and triggering builds a mono repo approach may not suit your needs</li><li>If your project is being worked on by multiple teams (e.g. back end &amp; front end teams) you may want to opt for a multi repo architecture</li><li>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</li><li>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</li><li>Uptime is easier to maintain with a mult-repo approach</li><li>Multi-repo allows for individual parts to be fixed/updated without taking down the service</li><li>Complex projects and supporting architecture (pipelines, APIs, DBs) are easier to manage with multi repo</li><li>Implementation (mono, multi, APIs, auth) matters far more than how the repositories are arranged</li></ul><h3>Source Code Repository License &amp; Ownership</h3>
+<ac:structured-macro ac:macro-id="5f5c56f3-5d6c-46cf-ad8f-f3ff3d2ece6b" ac:name="details" ac:schema-version="1"><ac:parameter ac:name="label" /><ac:rich-text-body><table class="wrapped"><colgroup><col /><col /></colgroup><tbody><tr><th>Status</th><td><div class="content-wrapper"><p><ac:structured-macro ac:macro-id="ddabb8ed-6687-4038-9868-5cdb89b54afd" ac:name="status" ac:schema-version="1"><ac:parameter ac:name="colour">Green</ac:parameter><ac:parameter ac:name="title">Document</ac:parameter></ac:structured-macro></p></div></td></tr><tr><th>Stakeholders</th><td><div class="content-wrapper"><p><ac:link><ri:user ri:userkey="0ea233ad7d54d280017d9b830b4f0008" /></ac:link> <ac:link><ri:user ri:userkey="0ea2648d4daa8a64014dbb62f12c0008" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a47638a3dd01776904055a002b" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a46ee6708d017011b1fa350019" /></ac:link> <ac:link><ri:user ri:userkey="0ea2648d4dfcf8d0014ed0ce7d8b0016" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a467b803370167d33966e10002" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a463ea71d2016485f6bd890006" /></ac:link> <ac:link><ri:user ri:userkey="0ea233a46d11a926016d3b1bc2330006" /></ac:link>  </p></div></td></tr><tr><th>Description</th><td>General guidance and recommendations for source code repositories</td></tr><tr><th>Outcome</th><td><br /></td></tr><tr><th>Owner</th><td>IITD Architecture</td></tr></tbody></table></ac:rich-text-body></ac:structured-macro><h3 style="text-align: left;">Source Code Repository Types</h3><table class="wrapped"><colgroup><col /><col /><col /><col /></colgroup><thead><tr><th style="text-align: left;"><p>Repository Type</p></th><th style="text-align: left;"><p>When to Use</p></th><th style="text-align: left;"><p>Key Contacts</p></th><th style="text-align: left;"><p>Notes</p></th></tr></thead><tbody><tr><td style="text-align: left;">Subversion</td><td style="text-align: left;">Never</td><td style="text-align: left;"><br /></td><td style="text-align: left;">Subversion is deprecated, do not create any new repositories.</td></tr><tr><td style="text-align: left;">BitBucket</td><td style="text-align: left;">Closed, internal</td><td style="text-align: left;"><br /></td><td style="text-align: left;">Manual, complex, (currently) in-house.  Works with RFC/RFD process and JIRA.  Very customizable.</td></tr><tr><td style="text-align: left;">Github</td><td style="text-align: left;">Whenever possible</td><td style="text-align: left;"><br /></td><td style="text-align: left;"><p>Ideal for automation, open source.  Industry leader in most significant areas.  Very unconstrained. </p><p>see <a href="https://github.com/bcgov/BC-Policy-Framework-For-GitHub">https://github.com/bcgov/BC-Policy-Framework-For-GitHub</a></p></td></tr></tbody></table><p style="text-align: left;"><br /></p><p style="text-align: left;"><strong><ac:inline-comment-marker ac:ref="5a0cc7cd-f337-4f2f-a89e-61a266e60848">GitHub</ac:inline-comment-marker></strong>:</p><ul style="text-align: left;"><li><ac:inline-comment-marker ac:ref="6098f703-1f1c-4848-ba43-9fa85bb1dfbe">Predominant</ac:inline-comment-marker> <ac:inline-comment-marker ac:ref="752650ae-d7bd-41ef-9340-212201f6fbca">SCM</ac:inline-comment-marker> system used in BC Government</li><li>Free code repositories for open source projects</li><li>Free GitHub Actions for open source projects</li><li>Marketplace provides an incredible amount of<span> </span><a class="external-link" href="https://github.com/marketplace" rel="nofollow">technologies and services</a></li><li><ac:inline-comment-marker ac:ref="08fba09a-8dda-42bd-a786-721b50d6e0d0">Free container registry</ac:inline-comment-marker> (*within GitHub Actions)<ul><li>Images can be consumed by OpenShift/Kubernetes, AWS, Azure, Podman/Docker and more</li></ul></li><li>Biggest code repository system<ul><li>Highest visibility, globally and locally</li><li>Largest developer ecosystem</li><li>Largest reach for talent</li><li>Largest base for tooling and 3rd party app support</li></ul></li><li>Functions as a live resume for developers</li><li><span>System for templating and <a href="https://github.com/bcgov/greenfield-template">starting projects quickly</a></span></li><li><span>Content is easily discovered by public search (e.g. Google)</span></li><li><span>Open source content is readily available, login-free</span></li><li><span>Visibility encourages collaboration and <ac:inline-comment-marker ac:ref="28cfe6b2-f658-4cf9-a26f-7335761d513c">discourages undesirable behavior</ac:inline-comment-marker></span></li><li><span><ac:inline-comment-marker ac:ref="4ccd2002-28da-4d86-a987-b7e1585233bc">Sensible patterns</ac:inline-comment-marker> prevent code from being deployed to production, but not merged</span></li><li><span><ac:inline-comment-marker ac:ref="b3921df1-2f84-4521-b6b1-a24e1adf23fc">Versatility</ac:inline-comment-marker> allows teams to tailor their processes, increasing productivity</span></li></ul><p><span>For practices on using GitHub see: <ac:link><ri:page ri:content-title="GitHub Repository Best Practices" /></ac:link></span></p><p><br /></p><p><span><strong>BitBucket</strong>:</span></p><ul style="list-style-type: square;"><li>JIRA integration</li><li>Connections are stronger between teams and interal processes, e.g. <ac:inline-comment-marker ac:ref="be09513a-ffbd-4ba6-a699-e89516c57535">RFC/RFD</ac:inline-comment-marker></li><li>Fine-grained control, e.g.:<ul style="list-style-type: square;"><li>Prevent even repo administrators from merging code or side-stepping requirements</li><li>Asphyxiate contractors with red tape until code is abandoned and/or overwritten</li></ul></li><li>Currently on-premise, working Jenkins and minimal firewall/networking changes</li><li>Potential shift to cloud will require similar admin and network changes to GitHub</li></ul><p><br /></p><p><strong>Subversion (SVN)</strong>:</p><ul style="list-style-type: square;"><li>Lessened need to retrain on legacy projects, some are comfortable/familiar</li></ul><h3>Source Code Repository Naming</h3><ul><li>Github: prefix each repository with &quot;nr-&quot;<ul><li>e.g. nr-&lt;app-name&gt;</li><li>e.g. nr-fom-api</li></ul></li></ul><h3>Diagrams</h3><ul><li>All repositories should have a .diagrams folder in the root of the repo. This folder should have at least:<br /><ul><li>1x application architecture diagram in the source file format .drawio.xml</li><li>1x system integration and data flow diagram in the source file format .drawio.xml</li><li>1x architecture diagram in the file format .png for each .drawio.xml diagram</li></ul></li></ul><h3>Source Code Repository Topics</h3><ul><li><span class="ILfuVd"><span class="hgKElc">Topics are labels that create subject-based connections between GitHub repositories and let you explore projects by type, technology, and more</span></span></li><li><span class="ILfuVd"><span class="hgKElc">putting nrs as a topic in the repos.</span></span></li></ul><h3>Mono Repo vs Multi Repo?</h3><ul><li><span class="hs_cos_wrapper hs_cos_wrapper_meta_field hs_cos_wrapper_type_rich_text">TL;DR - mono initially, multi with growth (e.g. +services, micro-service, APIs)</span></li><li><span class="hs_cos_wrapper hs_cos_wrapper_meta_field hs_cos_wrapper_type_rich_text">In a mono repo approach, all services and codebase are kept in a single repository</span></li><li>Generally speaking, mono repos minimize dependency management</li><li>If you have multiple services sharing the same libraries or common code, you may want to opt for a mono repo architecture</li><li>If you predict that your project will be extremely large or complex, a mono repo approach may become untenable over time</li><li>If you have a large team with multi developers doing commits and triggering builds a mono repo approach may not suit your needs</li><li>If your project is being worked on by multiple teams (e.g. back end &amp; front end teams) you may want to opt for a multi repo architecture</li><li>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</li><li>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</li><li>Uptime is easier to maintain with a mult-repo approach</li><li>Multi-repo allows for individual parts to be fixed/updated without taking down the service</li><li>Complex projects and supporting architecture (pipelines, APIs, DBs) are easier to manage with multi repo</li><li>Implementation (mono, multi, APIs, auth) matters far more than how the repositories are arranged</li></ul><h3>Source Code Repository License &amp; Ownership</h3>