diff --git a/docs/adr/ADR-004_Agree_CICD_pipeline_structure.md b/docs/adr/ADR-004_Agree_CICD_pipeline_structure.md new file mode 100644 index 00000000..5fdf6e81 --- /dev/null +++ b/docs/adr/ADR-004_Agree_CICD_pipeline_structure.md @@ -0,0 +1,81 @@ +# ADR-004: Agree CI/CD pipeline structure + +>| | | +>| ------------ | --- | +>| Date | `12/09/2022` | +>| Status | `RFC` | +>| Deciders | `Engineering` | +>| Significance | `Construction techniques` | +>| Owners | `?` | + +--- + +- [ADR-004: Agree CI/CD pipeline structure](#adr-004-agree-cicd-pipeline-structure) + - [Context](#context) + - [Decision](#decision) + - [Assumptions](#assumptions) + - [Drivers](#drivers) + - [Options](#options) + - [Outcome](#outcome) + - [Rationale](#rationale) + - [Consequences](#consequences) + - [Compliance](#compliance) + - [Tags](#tags) + +## Context + +Requirements: + +- Implement the exemplar CI/CD pipeline using GitHub workflows and actions +- Incorporate the four main CI/CD stages, which are as follows: + 1. Commit, max. execution time 2 mins + 2. Test, max. execution time 5 mins + 3. Build, max. execution time 3 mins + 4. Acceptance, max. execution time 10 mins +- Provide `publish`, `deploy` and `rollback` workflows as the complementary processes +- Maintain simplicity in the pipeline but ensure it is scalable and extensible for larger projects +- Enable parallel execution of jobs to speed up the overall process +- Prevent the workflow from being triggered twice, i.e. when pushing to a branch with an existing pull request +- Implement good CI/CD practices, such as: + - Setting the build time variables at the start of the process + - Storing the tooling versions like Terraform, Python and Node.js in the `./.tools-version` file (dependency management) + - Storing the software/project version in the `VERSION` file at the project root-level or in an artifact directory + - Keeping the main workflow modular + - Ensuring a timeout is set for each job + - Listing environment variables + - Making actions portable, e.g. allowing them to be run on a workstation or Azure DevOps using scripts + - Providing testable CI/CD building blogs + +## Decision + +### Assumptions + +TODO: state the assumptions + +### Drivers + +TODO: list the drivers + +### Options + +TODO: table, SEE: the [CI/CD pipeline](../developer-guides/CICD_pipeline.md) high-level design. + +### Outcome + +TODO: decision outcome + +### Rationale + +TODO: rationale + +## Consequences + +TODO: consequences + +## Compliance + +TODO: how the success is going to be measured + +## Tags + +`#maintainability, #testability, #deployability, #modularity, #simplicity, #reliability` diff --git a/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md b/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md deleted file mode 100644 index 81f5c54a..00000000 --- a/docs/adr/ADR-XXX_Agree_CICD_pipeline_structure.md +++ /dev/null @@ -1,101 +0,0 @@ -# ADR-XXX: Agree CI/CD pipeline structure - ->| | | ->| ------------ | --- | ->| Date | `dd/mm/YYYY` _when the decision was last updated_ | ->| Status | `RFC by dd/mm/YYYY, Proposed, In Discussion, Pending Approval, Withdrawn, Rejected, Accepted, Deprecated, ..., Superseded by ADR-XXX or Supersedes ADR-XXX` | ->| Deciders | `Tech Radar, Engineering, Architecture, Solution Assurance, Clinical Assurance, Technical Review and Governance, Information Governance, Cyber Security, Live Services Board,` ... | ->| Significance | `Structure, Nonfunctional characteristics, Dependencies, Interfaces, Construction techniques,` ... | ->| Owners | | - ---- - -- [ADR-XXX: Agree CI/CD pipeline structure](#adr-xxx-agree-cicd-pipeline-structure) - - [Context](#context) - - [Decision](#decision) - - [Assumptions](#assumptions) - - [Drivers](#drivers) - - [Options](#options) - - [Outcome](#outcome) - - [Rationale](#rationale) - - [Consequences](#consequences) - - [Compliance](#compliance) - - [Notes](#notes) - - [Actions](#actions) - - [Tags](#tags) - -## Context - -Describe the context and the problem statement. Is there a relationship to other decisions previously made? Are there any dependencies and/or constraints within which the decision will be made? Do these need to be reviewed or validated? Please, note that environmental limitations or restrictions such as accepted technology standards, commonly recognised and used patterns, engineering and architecture principles, organisation policies, governance and so on, may as an effect narrow down the choices. This should also be explicitly documented, as this is a point-in-time decision with the intention of being able to articulate it clearly and justify it later. - -Requirements: - -- Implement the exemplar CI/CD pipeline using GitHub workflows and actions -- Incorporate the four main CI/CD stages, which are as follows: - 1. Commit, max. execution time 2 mins - 2. Test, max. execution time 5 mins - 3. Build, max. execution time 3 mins - 4. Acceptance, max. execution time 10 mins -- Provide `publish` and `deploy` workflows as the complementary processes -- Maintain simplicity in the pipeline but ensure it is scalable and extensible for larger projects -- Enable parallel execution of jobs to speed up the overall process -- Prevent the workflow from being triggered twice, i.e. when pushing to a branch with an existing pull request -- Implement good CI/CD practices, such as: - - Setting the build time variables at the start of the process - - Storing the tooling versions like Terraform, Python and Node.js in the `./.tools-version` file - - Storing the software/project version in the `./VERSION` file - - Keeping the main workflow modular - - Ensuring a timeout is set for each job - - Listing environment variables - - Making actions portable, e.g. allowing them to be run on a workstation or on Azure DevOps using external scripts - -![CD Pipeline Structure](../diagrams/CD%20Pipeline%20Structure.png) - -## Decision - -### Assumptions - -Summarise the underlying assumptions in the environment in which you make the decision. This could be related to technology changes, forecast of the monetary and non-monetary costs, further delivery commitments, impactful external drivers etc., and any known unknowns that translate to risks. - -### Drivers - -List the decision drivers that motivate this change or course of action. This may include any identified risks and residual risks after applying the decision. - -### Options - -Consider a comprehensive set of alternative options; provide weighting if applicable. - -### Outcome - -State the decision outcome as a result of taking into account all of the above. Is it a reversible or irreversible decision? - -### Rationale - -Provide a rationale for the decision that is based on weighing the options to ensure that the same questions are not going to be asked again and again unless the decision needs to be superseded. - -For non-trivial decisions a comparison table can be useful for the reviewer. Decision criteria down one side, options across the top. You'll likely find decision criteria come from the Drivers section above. Effort can be an important driving factor. You may have an intuitive feel for this, but reviewers will not. T-shirt sizing the effort for each option may help communicate. - -## Consequences - -Describe the resulting context, after applying the decision. All the identified consequences should be listed here, not just the positive ones. Any decision comes with many implications. For example, it may introduce a need to make other decisions as an effect of cross-cutting concerns; it may impact structural or operational characteristics of the software, and influence non-functional requirements; as a result, some things may become easier or more difficult to do because of this change. What are the trade-offs? - -What are the conditions under which this decision no longer applies or becomes irrelevant? - -## Compliance - -Establish how the success is going to be measured. Once implemented, the effect might lend itself to be measured, therefore if appropriate a set of criteria for success could be established. Compliance checks of the decision can be manual or automated using a fitness function. If it is the latter this section can then specify how that fitness function would be implemented and whether there are any other changes to the codebase needed to measure this decision for compliance. - -## Notes - -Include any links to existing epics, decisions, dependencies, risks, and policies related to this decision record. This section could also include any further links to configuration items within the project or the codebase, signposting to the areas of change. - -It is important that if the decision is sub-optimal or the choice is tactical or misaligned with the strategic directions the risk related to it is identified and clearly articulated. As a result of that, the expectation is that a [Tech Debt](./tech-debt.md) record is going to be created on the backlog. - -## Actions - -- [x] name, date by, action -- [ ] name, date by, action - -## Tags - -`#availability|#scalability|#elasticity|#performance|#reliability|#resilience|#maintainability|#testability|#deployability|#modularity|#simplicity|#security|#data|#cost|#usability|#accessibility|…` these tags are intended to be operational, structural or cross-cutting architecture characteristics to link to related decisions. diff --git a/docs/developer-guides/CICD_pipeline.md b/docs/developer-guides/CICD_pipeline.md index 17a6a55a..727fc8ea 100644 --- a/docs/developer-guides/CICD_pipeline.md +++ b/docs/developer-guides/CICD_pipeline.md @@ -241,25 +241,21 @@ flowchart LR flowchart LR subgraph branch_review["Branch review"] direction LR - bA("`**local**`") + bA("local") end subgraph pr_review["PR Review"] direction LR - prA["`**ephemeral** - dev environments`"] - prB["`automated acceptance - **test** environments`"] + prA["ephemeral
dev environments"] + prB["automated acceptance
test environments"] prA --> prB end subgraph deploy1["Deploy (high-instance)"] direction LR - d1A["`**non-prod** - environments`"] + d1A["non-prod
environments"] end subgraph deploy2["Deploy (Live)"] direction LR - d2A["`**prod** - environment`"] + d2A["prod environment"] end branch_review --> pr_review pr_review --> deploy1