Adding or updating the confluence pages

confluence/pages/Coding_Patterns_&_Practices/README.md

@@ -1 +1 @@
-<table class="wrapped"><colgroup><col /><col /></colgroup><tbody><tr><th>Status</th><td><div class="content-wrapper"><p>Document</p></div></td></tr><tr><th>Stakeholders</th><td>NRIDS Architecture, Development &amp; Digital Services, NRM Product Teams</td></tr><tr><th>Description</th><td>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.</td></tr><tr><th>Outcome</th><td>Consistent point of reference for onboarding new product teams into the NRM's.</td></tr><tr><th>Owner</th><td>NRIDS (DDS, Architecture)</td></tr></tbody></table><p><br /></p><p><strong>Languages Supported</strong></p><p>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, <ac:inline-comment-marker ac:ref="caa2b41e-e793-4e43-81aa-ffda13c07472">Go</ac:inline-comment-marker>)</p><p><br /></p><p><strong>Native Deployments</strong></p><p>Some Languages are interpreted by their runtime ex:(java on JVM, python, javascript, etc..) whereas some languages are compiled (Golang, Rust).</p><p>Use native(static binary) deployments wherever available. for ex: it is a <strong>MUST </strong>for teams using Java to deploy using GraalVM native image without the overhead of JVM interpreter. </p><p>Focus on the scale-out vs scale-up as deployments are into containers or serverless.</p><p><br /></p><p><strong>Code Design Patterns and Principles</strong></p><ul><li>Apply SOLID and DRY principles. (<a href="https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/">https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english</a>, <a href="https://www.baeldung.com/cs/dry-software-design-principle">https://www.baeldung.com/cs/dry-software-design-principle</a>)</li><li>Use Composition over inheritance as much as possible.</li><li>Use IOC(Inversion of Control) pattern for dependency Injection, following constructor-based injection over setter or field-based injection.</li><li>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.<ul><li>(controller/endpoints → service → repository/active record → entity/query/mutation)</li><li>The controller should call the service or multiple services inside a transaction boundary to perf</li><li>orm the atomic operation.</li><li>The Service Layer MUST have a transactional context.</li></ul></li><li>Use Lazy Loading and Cascading in ORM to avoid fetching child entities unnecessarily and also make sure the mutations are cascaded as well.</li><li>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.</li><li>Follow The Twelve-Factor App standards -<span> </span><a class="external-link" href="https://12factor.net/" rel="nofollow">https://12factor.net/</a></li><li>Use testcontainers(<a href="https://www.testcontainers.org/">https://www.testcontainers.org/</a>) or GHA services(<a href="https://docs.github.com/en/actions/using-containerized-services/about-service-containers">https://docs.github.com/en/actions/using-containerized-services/about-service-containers</a>) for integration TESTS which includes, databases, queues, cache etc...</li></ul><p><strong>Folder Structure and Naming Conventions</strong></p><ul><li>Establish and understand your folder structure, if using a template avoid reorganizing (eg. <a href="https://github.com/bcgov/quickstart-openshift">https://github.com/bcgov/quickstart-openshift</a>)</li><li>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})</li></ul><h3>Secret and Environment Variable Handling</h3><ul><li>Exercise the practice of least privilege (eg. Who can and should be able to access secrets) </li><li>Do not put sensitive information in the code, use a secret</li><li>Use environment variables when they may not be sensitive but change between environments (eg. Dev, Test, Prod)</li><li>Do not create secrets manually in Openshift.</li></ul><h3>Secure APIs</h3><ul><li>APIs should always be secured. This is generally achieved by using role based access based off their role validated via JWT.</li><li>The exception to this would be public APIs.</li></ul><h3>Error Handling</h3><ul><li>Gracefully handle errors</li><li>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)</li><li>Avoid generic language (eg. Error, review logs)</li></ul><p><br /></p><p><strong>Code Formatters and Plugins</strong></p><ul><li>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)</li><li>Share the IDE specific formatter in the GitHub to avoid conflicts</li></ul><h3>Infrastructure as Code</h3><ul><li>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.</li></ul><h3>Pipeline</h3><ul><li>Understand your DevOps pipeline (eg. What happens when I create a PR, merge a PR, how an image gets built, how code get tested)</li><li>Maintain your pipeline and align if possible to common practice (eg. <a href="https://github.com/bcgov/quickstart-openshift">https://github.com/bcgov/quickstart-openshift</a>)</li></ul><p><span style="letter-spacing: 0.0px;">The below was created using the </span><a class="external-link" href="https://github.com/bcgov/quickstart-openshift" rel="nofollow">QuickStart OpenShift</a><span style="letter-spacing: 0.0px;"> as a reference. Please refer to the repo for the most up to date information.</span></p><p><span style="letter-spacing: 0.0px;"><ac:structured-macro ac:name="drawio" ac:schema-version="1" ac:macro-id="d42cd46c-ee4c-46bb-a91b-c9155cf840b8"><ac:parameter ac:name="border">true</ac:parameter><ac:parameter ac:name="diagramName">Branching Strategy</ac:parameter><ac:parameter ac:name="simpleViewer">false</ac:parameter><ac:parameter ac:name="width" /><ac:parameter ac:name="links">auto</ac:parameter><ac:parameter ac:name="tbstyle">top</ac:parameter><ac:parameter ac:name="lbox">true</ac:parameter><ac:parameter ac:name="diagramWidth">1011</ac:parameter><ac:parameter ac:name="revision">1</ac:parameter><ac:parameter ac:name="" /></ac:structured-macro></span></p><p style="text-align: left;"><strong>GitHub PRs - Commits</strong></p><ul style="text-align: left;"><li>Follow the Conventional Commits for a better understanding -<span> </span><a class="external-link" href="https://www.conventionalcommits.org/en/v1.0.0/" rel="nofollow">https://www.conventionalcommits.org/en/v1.0.0/</a></li></ul><h3>PR Review and Practices</h3><ul><li>PR titles should follow a pattern (eg. &quot;#&lt;Ticket_number&gt;-Nice Description (#)&quot;)</li><li>A single PR should be for a single Feature/bug/hotfix/patch/etc and kept as small as possible and reasonable</li><li>Add appropriate labels established by your team. (eg. Adding labels to also indicate the applications being impacted by the PR, for instance, &quot;web&quot; or &quot;API&quot;)</li><li>Connect the issue using the button &quot;Connect Issue&quot;, if not available install the Chrome Extension<span> </span><a href="https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd" style="text-decoration: none;" rel="nofollow">ZenHub for GitHub</a><span> </span>or similar (this will help trace a completed task to the code modified)</li><li>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.</li><li>If you are a reviewer try to mark the comments as resolved to help the PR author to identify easily what is still missing.</li><li>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.</li><li>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)</li><li>Review according to best practices for the code and application. PRs are about code review (<strong>not people review</strong>)</li><li>Have a merging practice. (eg. Squash the commits before merging to keep the main timeline clean)</li><li>Clean up your branches (eg. Delete the branch after the merge is done (after merging<span> </span>do not reuse the branch))</li></ul><p><strong>Dependency Management</strong></p><ul><li>It is <u><strong>strongly recommended to keep dependencies updated</strong></u> with automated pull requests from tools like <u><strong>Renovate, Snyk or Dependabot</strong></u>.</li><li>This introduces new features, fix bugs, address vulnerabilities or improve performance, affecting the quality, security, and functionality of a project.</li><li>Regular dependency pull requests help to keep changes small, up to date and, of course, manageable.</li><li>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.</li></ul><p><br /></p>
+<table class="wrapped"><colgroup><col /><col /></colgroup><tbody><tr><th>Status</th><td><div class="content-wrapper"><p>Document</p></div></td></tr><tr><th>Stakeholders</th><td>NRIDS Architecture, Development &amp; Digital Services, NRM Product Teams</td></tr><tr><th>Description</th><td>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.</td></tr><tr><th>Outcome</th><td>Consistent point of reference for onboarding new product teams into the NRM's.</td></tr><tr><th>Owner</th><td>NRIDS (DDS, Architecture)</td></tr></tbody></table><p><br /></p><p><strong>Languages Supported</strong></p><p>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, <ac:inline-comment-marker ac:ref="caa2b41e-e793-4e43-81aa-ffda13c07472">Go</ac:inline-comment-marker>)</p><p><br /></p><p><strong>Native Deployments</strong></p><p>Some Languages are interpreted by their runtime ex:(java on JVM, python, javascript, etc..) whereas some languages are compiled (Golang, Rust).</p><p>Use native(static binary) deployments wherever available. for ex: it is a <strong>MUST </strong>for teams using Java to deploy using GraalVM native image without the overhead of JVM interpreter. </p><p>Focus on the scale-out vs scale-up as deployments are into containers or serverless.</p><p><br /></p><p><strong>Code Design Patterns and Principles</strong></p><ul><li>Apply SOLID and DRY principles. (<a href="https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english/">https://www.freecodecamp.org/news/solid-principles-explained-in-plain-english</a>, <a href="https://www.baeldung.com/cs/dry-software-design-principle">https://www.baeldung.com/cs/dry-software-design-principle</a>)</li><li>Use Composition over inheritance as much as possible.</li><li>Use IOC(Inversion of Control) pattern for dependency Injection, following constructor-based injection over setter or field-based injection.</li><li>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.<ul><li>(controller/endpoints → service → repository/active record → entity/query/mutation)</li><li>The controller should call the service or multiple services inside a transaction boundary to perf</li><li>orm the atomic operation.</li><li>The Service Layer MUST have a transactional context.</li></ul></li><li>Use Lazy Loading and Cascading in ORM to avoid fetching child entities unnecessarily and also make sure the mutations are cascaded as well.</li><li>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.</li><li>Follow The Twelve-Factor App standards -<span> </span><a class="external-link" href="https://12factor.net/" rel="nofollow">https://12factor.net/</a></li><li>Use testcontainers(<a href="https://www.testcontainers.org/">https://www.testcontainers.org/</a>) or GHA services(<a href="https://docs.github.com/en/actions/using-containerized-services/about-service-containers">https://docs.github.com/en/actions/using-containerized-services/about-service-containers</a>) for integration TESTS which includes, databases, queues, cache etc...</li></ul><p><strong>Folder Structure and Naming Conventions</strong></p><ul><li>Establish and understand your folder structure, if using a template avoid reorganizing (eg. <a href="https://github.com/bcgov/quickstart-openshift">https://github.com/bcgov/quickstart-openshift</a>)</li><li>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)</li></ul><h3>Secret and Environment Variable Handling</h3><ul><li>Exercise the practice of least privilege (eg. Who can and should be able to access secrets) </li><li>Do not put sensitive information in the code, use a secret</li><li>Use environment variables when they may not be sensitive but change between environments (eg. Dev, Test, Prod)</li><li>Do not create secrets manually in Openshift.</li></ul><h3>Secure APIs</h3><ul><li>APIs should always be secured. This is generally achieved by using role based access based off their role validated via JWT.</li><li>The exception to this would be public APIs.</li></ul><h3>Error Handling</h3><ul><li>Gracefully handle errors</li><li>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)</li><li>Avoid generic language (eg. Error, review logs)</li></ul><p><br /></p><p><strong>Code Formatters and Plugins</strong></p><ul><li>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)</li><li>Share the IDE specific formatter in the GitHub to avoid conflicts</li></ul><h3>Infrastructure as Code</h3><ul><li>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.</li></ul><h3>Pipeline</h3><ul><li>Understand your DevOps pipeline (eg. What happens when I create a PR, merge a PR, how an image gets built, how code get tested)</li><li>Maintain your pipeline and align if possible to common practice (eg. <a href="https://github.com/bcgov/quickstart-openshift">https://github.com/bcgov/quickstart-openshift</a>)</li></ul><p><span style="letter-spacing: 0.0px;">The below was created using the </span><a class="external-link" href="https://github.com/bcgov/quickstart-openshift" rel="nofollow">QuickStart OpenShift</a><span style="letter-spacing: 0.0px;"> as a reference. Please refer to the repo for the most up to date information.</span></p><p><span style="letter-spacing: 0.0px;"><ac:structured-macro ac:name="drawio" ac:schema-version="1" ac:macro-id="d42cd46c-ee4c-46bb-a91b-c9155cf840b8"><ac:parameter ac:name="border">true</ac:parameter><ac:parameter ac:name="diagramName">Branching Strategy</ac:parameter><ac:parameter ac:name="simpleViewer">false</ac:parameter><ac:parameter ac:name="width" /><ac:parameter ac:name="links">auto</ac:parameter><ac:parameter ac:name="tbstyle">top</ac:parameter><ac:parameter ac:name="lbox">true</ac:parameter><ac:parameter ac:name="diagramWidth">1011</ac:parameter><ac:parameter ac:name="revision">1</ac:parameter><ac:parameter ac:name="" /></ac:structured-macro></span></p><p style="text-align: left;"><strong>GitHub PRs - Commits</strong></p><ul style="text-align: left;"><li>Follow the Conventional Commits for a better understanding -<span> </span><a class="external-link" href="https://www.conventionalcommits.org/en/v1.0.0/" rel="nofollow">https://www.conventionalcommits.org/en/v1.0.0/</a></li></ul><h3>PR Review and Practices</h3><ul><li>PR titles should follow a pattern (eg. &quot;#Ticket Number - Nice Description (#)&quot;)</li><li>A single PR should be for a single Feature/bug/hotfix/patch/etc and kept as small as possible and reasonable</li><li>Add appropriate labels established by your team. (eg. Adding labels to also indicate the applications being impacted by the PR, for instance, &quot;web&quot; or &quot;API&quot;)</li><li>Connect the issue using the button &quot;Connect Issue&quot;, if not available install the Chrome Extension<span> </span><a href="https://chrome.google.com/webstore/detail/zenhub-for-github/ogcgkffhplmphkaahpmffcafajaocjbd" style="text-decoration: none;" rel="nofollow">ZenHub for GitHub</a><span> </span>or similar (this will help trace a completed task to the code modified)</li><li>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.</li><li>If you are a reviewer try to mark the comments as resolved to help the PR author to identify easily what is still missing.</li><li>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.</li><li>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)</li><li>Review according to best practices for the code and application. PRs are about code review (<strong>not people review</strong>)</li><li>Have a merging practice. (eg. Squash the commits before merging to keep the main timeline clean)</li><li>Clean up your branches (eg. Delete the branch after the merge is done (after merging<span> </span>do not reuse the branch))</li></ul><p><strong>Dependency Management</strong></p><ul><li>It is <u><strong>strongly recommended to keep dependencies updated</strong></u> with automated pull requests from tools like <u><strong>Renovate, Snyk or Dependabot</strong></u>.</li><li>This introduces new features, fix bugs, address vulnerabilities or improve performance, affecting the quality, security, and functionality of a project.</li><li>Regular dependency pull requests help to keep changes small, up to date and, of course, manageable.</li><li>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.</li></ul><p><br /></p>