Merge branch 'main' into mikewo/updating-python-recipe

.github/workflows/mega-linter.yml

@@ -51,7 +51,7 @@ jobs:
       # Upload MegaLinter artifacts
       - name: Archive production artifacts
         if: always()
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
           name: MegaLinter reports
           path: |

README.md

@@ -19,11 +19,11 @@ This is our playbook. All contributions welcome! Please feel free to submit a [p
 
 ## "The" Checklist
 
-If you do nothing else follow the [Engineering Fundamentals Checklist](docs/ENG-FUNDAMENTALS-CHECKLIST.md)! It's here to help follow the Engineering Fundamentals.
+If you do nothing else follow the [Engineering Fundamentals Checklist](docs/engineering-fundamentals-checklist.md)! It's here to help follow the Engineering Fundamentals.
 
 ## Structure of a Sprint
 
-A [breakdown of sections](docs/SPRINT-STRUCTURE.md) according to the structure of an Agile sprint.
+A [breakdown of sections](docs/the-first-week-of-an-ise-project.md) according to the structure of an Agile sprint.
 
 ## General Guidance
 
@@ -38,19 +38,19 @@ A [breakdown of sections](docs/SPRINT-STRUCTURE.md) according to the structure o
 * Report product issues found and provide clear and repeatable engineering feedback!
 * We all own our code and each one of us has an obligation to make all parts of the solution great.
 
-## QuickLinks
+## Resources
 
-* [Engineering Fundamentals Checklist](docs/ENG-FUNDAMENTALS-CHECKLIST.md)
-* [Structure of a Sprint](docs/SPRINT-STRUCTURE.md)
+* [Engineering Fundamentals Checklist](docs/engineering-fundamentals-checklist.md)
+* [The first week of an ISE project](docs/the-first-week-of-an-ise-project.md)
 
 ## Engineering Fundamentals
 
-* [Accessibility](docs/accessibility/README.md)
+* [Accessibility](docs/non-functional-requirements/accessibility.md)
 * [Agile Development](docs/agile-development/README.md)
 * [Automated Testing](docs/automated-testing/README.md)
 * [Code Reviews](docs/code-reviews/README.md)
-* [Continuous Delivery (CD)](docs/continuous-delivery/README.md)
-* [Continuous Integration (CI)](docs/continuous-integration/README.md)
+* [Continuous Delivery (CD)](docs/CI-CD/continuous-delivery.md)
+* [Continuous Integration (CI)](docs/CI-CD/continuous-integration.md)
 * [Design](docs/design/readme.md)
 * [Developer Experience](docs/developer-experience/README.md)
 * [Documentation](docs/documentation/README.md)
@@ -59,12 +59,12 @@ A [breakdown of sections](docs/SPRINT-STRUCTURE.md) according to the structure o
 * [Security](docs/security/README.md)
 * [Privacy](docs/privacy/README.md)
 * [Source Control](docs/source-control/README.md)
-* [Reliability](docs/reliability/README.md)
+* [Reliability](docs/non-functional-requirements/reliability.md)
 
 ## Fundamentals for Specific Technology Areas
 
 * [Machine Learning Fundamentals](docs/machine-learning/README.md)
-* [User-Interface Engineering](docs/user-interface-engineering/README.md)
+* [User-Interface Engineering](docs/UI-UX/README.md)
 
 ## Contributing
 

docs/.pages

@@ -0,0 +1,10 @@
+nav:
+  - ISE Engineering Fundamentals Playbook: README.md
+  - Engineering Fundamentals Checklist: engineering-fundamentals-checklist.md
+  - The First Week of an ISE Project: the-first-week-of-an-ise-project.md
+  - Who is ISE?: ISE.md
+  - Agile Development: agile-development
+  - Automated Testing: automated-testing
+  - CI/CD: CI-CD
+  - ...
+  - UI/UX: UI-UX

docs/continuous-integration/CICD.md → docs/CI-CD/README.md

@@ -1,10 +1,10 @@
-# Continuous Integration and Delivery
+# Continuous Integration and Continuous Delivery
 
-Continuous Integration is the engineering practice of frequently committing code in a shared repository, ideally several times a day, and performing an automated build on it. These changes are built with other simultaneous changes to the system, which enables early detection of integration issues between multiple developers working on a project. Build breaks due to integration failures are treated as the highest priority issue for all the developers on a team and generally work stops until they are fixed.
+[**Continuous Integration (CI)**](./continuous-integration.md) is the engineering practice of frequently committing code in a shared repository, ideally several times a day, and performing an automated build on it. These changes are built with other simultaneous changes to the system, which enables early detection of integration issues between multiple developers working on a project. Build breaks due to integration failures are treated as the highest priority issue for all the developers on a team and generally work stops until they are fixed.
 
 Paired with an automated testing approach, continuous integration also allows us to also test the integrated build such that we can verify that not only does the code base still build correctly, but also is still functionally correct. This is also a best practice for building robust and flexible software systems.
 
-Continuous Delivery takes the Continuous Integration concept further to also test deployments of the integrated code base on a replica of the environment it will be ultimately deployed on. This enables us to learn early about any unforeseen operational issues that arise from our changes as quickly as possible and also learn about gaps in our test coverage.
+[**Continuous Delivery (CD)**](./continuous-delivery.md) takes the **Continuous Integration (CI)** concept further to also test deployments of the integrated code base on a replica of the environment it will be ultimately deployed on. This enables us to learn early about any unforeseen operational issues that arise from our changes as quickly as possible and also learn about gaps in our test coverage.
 
 The goal of all of this is to ensure that the main branch is always shippable, meaning that we could, if we needed to, take a build from the main branch of our code base and ship it on production.
 
@@ -14,6 +14,23 @@ Our expectation is that CI/CD should be used in all the engineering projects tha
 
 For a much deeper understanding of all of these concepts, the books [Continuous Integration](https://www.amazon.com/Continuous-Integration-Improving-Software-Reducing/dp/0321336380) and [Continuous Delivery](https://www.amazon.com/gp/product/0321601912) provide a comprehensive background.
 
+## Why CI/CD
+
+- We want to have an automated build and deployment of our software
+- We want automated configuration of all components
+- We want to be able to quickly re-build the environment from scratch in case of disaster
+- We want the latest version of the code to always be deployed to our dev/test environments
+- We want a reliable release strategy, where the policies for release are well understood by all
+
+## The Fundamentals
+
+- We run a quality pipeline (with linting, unit tests etc.) on each PR/update of the main branch
+- All cloud resources (including secrets and permissions) are provisioned through infrastructure as code templates – ex. Terraform, Bicep (ARM), Pulumi etc.
+- All release candidates are deployed to a non-production environment through an automated process (ex Azure DevOps or Github pipelines)
+- Releases are deployed to the production environment through an automated process
+- Release rollbacks are carried out through a repeatable process
+- Our release pipeline runs automated tests, validating all release candidate artifact(s) end-to-end against a non-production environment
+
 ## Tools
 
 ### Azure Pipelines

docs/continuous-delivery/README.md → docs/CI-CD/continuous-delivery.md

@@ -49,15 +49,15 @@ Code changes released into the *test* environment typically targets the main bra
 
 The very first deployment of any application should be showcased to the customer in a production-like environment (*UAT*) to solicit feedback early. The UAT environment is used to obtain product owner sign-off acceptance to ultimately promote the release to production.
 
-#### Criteria for a production-like environment
+#### Criteria for a Production-Like Environment
 
 * Runs the same operating system as production.
 * Has the same software installed as production.
 * Is sized and configured the same way as production.
 * Mirrors production's networking topology.
 * Simulated production-like load tests are executed following a release to surface any latency or throughput degradation.
 
-#### Modeling your Release Pipeline
+#### Modeling Your Release Pipeline
 
 It's critical to model your test and release process to establish a common understanding between the application engineers and customer stakeholders. Specifically aligning expectations for how many cloud environments need to be pre-provisioned as well as defining sign-off gate roles and responsibilities.
 
@@ -85,7 +85,7 @@ The stages within your release workflow are ultimately testing a version of your
 
 A release should be running for a period of time before it's considered live and allowed to accept user traffic. These *warm up* activities may include application server(s) and database(s) pre-fill any dependent cache(s) as well as establish all service connections (eg *connection pool allocations, etc*).
 
-#### Pre-production releases
+#### Pre-production Releases
 
 Application release candidates should be deployed to a staging environment similar to production for carrying out final manual/automated tests (*including capacity testing*). Your production and staging / pre-prod cloud environments should be setup at the beginning of your project.
 
@@ -135,13 +135,13 @@ Canary releases simplify rollbacks as you can avoid routing users to bad applica
 
 Try to limit the number of versions of your application running parallel in production, as it can complicate maintenance and monitoring controls.
 
-### Low code solutions
+### Low Code Solutions
 
 Low code solutions have increased their participation in the applications and processes and because of that it is required that a proper conjunction of disciplines improve their development.
 
-Here is a guide for [continuous deployment for Low Code Solutions](low-code-solutions/README.md).
+Here is a guide for [continuous deployment for Low Code Solutions](recipes/cd-on-low-code-solutions.md).
 
-## References
+## Resources
 
 * [Continuous Delivery](https://www.continuousdelivery.com/) by Jez Humble, David Farley.
 * [Continuous integration vs. continuous delivery vs. continuous deployment](https://www.atlassian.com/continuous-delivery/principles/continuous-integration-vs-delivery-vs-deployment)