diff --git a/golden paths/01-start-a-new-repository.md b/golden paths/01-start-a-new-repository.md new file mode 100644 index 00000000..0e86f95a --- /dev/null +++ b/golden paths/01-start-a-new-repository.md @@ -0,0 +1,58 @@ +# Golden Path: Start a New Repository + +Use this when a team is creating a new service or standing up a new codebase. + +## Outcome + +You finish with a repository that is ready for collaborative delivery, review, +automation, and secure change control. + +## Steps + +1. Create the repository in an approved source control platform. + Use GitHub under the official UKHO organisation where possible. Set the + default branch to `main`. +2. Add the baseline repository files. + Include `README.md`, `CONTRIBUTING.md`, `LICENSE`, `SECURITY.md`, and + `CODEOWNERS`. +3. Set repository access through teams, not individuals. + Avoid creating a single point of failure in repository ownership and access. +4. Enable branch protection on `main`. + Require pull requests, approvals, conversation resolution, required status + checks, and up-to-date branches before merge. +5. Decide the merge strategy. + Prefer `Squash and merge` so the main branch stays clean and pull requests + remain the primary review record. +6. Enable code security automation. + Turn on dependency alerts and automated dependency updates where supported. +7. Add build and release definitions as code. + Store pipeline YAML in source control from the start. +8. Define working conventions. + Use GitHub Flow, branch names of the form + `{ticket_number}/{type}-{description}`, and concise commit messages that + answer `Applying this change will...`. +9. Confirm the team definition of done. + Include code review, unit testing, documentation, and security checks. + +## Exit Criteria + +- The repository lives in an approved source control platform. +- `main` is protected. +- Pull requests are the only route into `main`. +- Ownership and access are team-based. +- Required repository files exist. +- Pipeline YAML is versioned with the code. + +## Policy Basis + +- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md) +- [Repository Setup Policy](../software-engineering-policies/SourceControl/RepositorySetupPolicy.md) +- [Branch Protection Policy](../software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md) +- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md) + +## Anti-Patterns + +- Committing directly to `main` +- Granting permanent write access to named individuals instead of teams +- Creating a repository without baseline documentation +- Keeping pipelines outside source control diff --git a/golden paths/02-deliver-a-code-change.md b/golden paths/02-deliver-a-code-change.md new file mode 100644 index 00000000..fe5424f7 --- /dev/null +++ b/golden paths/02-deliver-a-code-change.md @@ -0,0 +1,62 @@ +# Golden Path: Deliver a Code Change + +Use this for routine feature, enhancement, and bug-fix delivery. + +## Outcome + +You move a change from idea to merge with review, traceability, tests, and +security controls intact. + +## Steps + +1. Start from a tracked work item. + Every change should link back to a ticket or equivalent work item. +2. Decide whether to pair. + Prefer paired working when it is practical, especially for implementation, + troubleshooting, and release activities. +3. Create a short-lived branch from `main`. + Follow the pattern `{ticket_number}/{type}-{description}`. +4. Keep commits small and clear. + Each commit message should answer `Applying this change will...`. +5. Add or update automated tests with the code. + New non-trivial code must be covered by unit tests, and tests must be checked + in with the subject code. +6. Keep test coverage healthy. + Any reduction in coverage should be justified. +7. Update documentation as part of the same change. + If the change affects architecture, build, deployment, configuration, or + supportability, update the relevant system documentation. +8. Open a pull request before merge. + Use a title based on the work item, describe what changed, why it changed, + how it was tested, and any important reviewer context. +9. Complete peer review from source control. + All changes must be reviewed before merge, and review evidence must be kept + in the tooling. +10. Resolve review feedback before merge. + Do not treat the work item as done until the review is complete and any + follow-up changes are finished. + +## Exit Criteria + +- The change is linked to a work item. +- The branch follows the agreed naming convention. +- Tests were added or updated with the code. +- Documentation changed where needed. +- The pull request was reviewed and approved. +- The code merged through the protected mainline path. + +## Policy Basis + +- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md) +- [Pair Programming Policy](../software-engineering-policies/PairProgramming/PairProgrammingPolicy.md) +- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md) +- [Unit Testing Policy](../software-engineering-policies/UnitTesting/UnitTestingPolicy.md) +- [System Documentation Policy](../software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md) +- [Test Strategy](../quality-assurance/test-strategy.md) + +## Anti-Patterns + +- Large pull requests with unrelated changes +- Review outside source control +- Merging before review completes +- Adding functional code without automated tests diff --git a/golden paths/03-release-through-a-pipeline.md b/golden paths/03-release-through-a-pipeline.md new file mode 100644 index 00000000..8729f0ac --- /dev/null +++ b/golden paths/03-release-through-a-pipeline.md @@ -0,0 +1,63 @@ +# Golden Path: Release Through a Pipeline + +Use this when defining or evolving a build and release pipeline for a UKHO +digital product. + +## Outcome + +You operate a pipeline that is automated, repeatable, secure, and controlled. + +## Steps + +1. Store the pipeline as code. + Use YAML compatible with Azure Pipelines or GitHub workflows. +2. Model the minimum environment path. + Plan for at least development or engineering, formal test, and live. +3. Keep environments aligned. + Treat the three-environment model as the minimum expected baseline for current + and future products unless a justified exception exists. +4. Use approved secret handling. + Store non-secret values in a standard variable library and back secrets with + Azure Key Vault or the equivalent approved secret store. +5. Automate quality gates in build. + Include dependency checks, SAST verification, container scanning where + relevant, and unit tests. +6. Automate functional verification in non-live environments. + Run functional tests in development environments and broader integration or + end-to-end coverage in formal test environments. +7. Protect the release path to production. + Production deployments should only come from `main`, and `main` must be + protected by pull request review and required checks. +8. Set approval controls deliberately. + Prefer approvals on service connections and variable libraries instead of + relying only on environment approvals in YAML. +9. Design for idempotency and loose coupling. + The pipeline should be repeatable and each service should be deployable in + isolation. +10. Threat model the pipeline. + Treat the pipeline itself as an attack surface and review threats as the + design evolves. + +## Exit Criteria + +- Pipeline YAML is in source control. +- The minimum environment flow exists. +- Secrets are not stored directly in the pipeline. +- Build and release checks are automated. +- Production deploys only from `main`. +- Threat modelling has been considered for the pipeline design. + +## Policy Basis + +- [Baseline Pipeline Policy](../software-engineering-policies/Pipelines/Baseline_Policy.md) +- [Source Control Policy](../software-engineering-policies/SourceControl/SourceControlPolicy.md) +- [Branch Protection Policy](../software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md) +- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md) +- [Test Strategy](../quality-assurance/test-strategy.md) + +## Anti-Patterns + +- Manual release steps that could be automated +- Secret values embedded in YAML +- Deploying to production from feature branches +- Pipelines that depend on another product pipeline to succeed diff --git a/golden paths/04-adopt-or-update-a-dependency.md b/golden paths/04-adopt-or-update-a-dependency.md new file mode 100644 index 00000000..1cf673b8 --- /dev/null +++ b/golden paths/04-adopt-or-update-a-dependency.md @@ -0,0 +1,79 @@ +# Golden Path: Adopt or Update a Dependency + +Use this when introducing a new third-party package, upgrading an existing one, +or deciding whether an open-source component is acceptable. + +## Outcome + +You can adopt or update a dependency with licensing, maintenance, and security +checks completed before release, with remediation and exceptions tracked in an +auditable way. + +## Steps + +1. Confirm the dependency is necessary. + Reuse is encouraged, but the package should solve a real problem better than + building and maintaining custom code. +2. Validate the package source. + Use an approved package management tool or repository. +3. Check the license. + The license must be on the approved list or formally escalated for review. +4. Review open-source suitability. + Consider governance, maintenance activity, contribution model, maturity, and + whether the package is effectively open-core. +5. Assess security exposure. + Cross-reference known vulnerabilities and ensure the designated dependency + scanning tool runs before production release. +6. Ensure active dependency management tooling is enabled. + Use Snyk, Dependabot, or both, and confirm dependency checks are active for + the repository. Enable Dependabot alerts, security updates, and version + updates where applicable. +7. Set or confirm the failure threshold. + The team should agree what vulnerability level prevents release and must be + able to prove the pipeline blocks release when that threshold is breached. +8. Prioritise remediation by severity and business impact. + Assess and remediate dependency vulnerabilities in line with internal + vulnerability management policy timescales (POL218). +9. Track remediation in the team backlog. + Link remediation work items to pull requests so there is a clear audit trail + from issue discovery to fix. +10. Record exceptions explicitly. + If a vulnerability is suppressed or release proceeds with known risk, record + the reason, reviewer context, and next review date where appropriate. +11. Escalate when timelines cannot be met. + If remediation cannot be delivered in policy timescales, define interim + mitigations, assign an owner, and escalate through the Security Champion + and/or Lead Technical Security Engineer (Security). +12. Put the change through normal review. + Third-party component changes must be reviewed by the Lead Engineer. +13. Keep dependency evidence buildable and reportable. + It must be possible to report on included licenses at build time. + +## Exit Criteria + +- The package comes from an approved source. +- The license is approved or formally excepted. +- Dependency and vulnerability checks are active in the repository. +- Snyk, Dependabot, or both are configured and operating. +- The release gate for vulnerable dependencies is defined. +- Remediation is tracked in backlog items linked to pull requests. +- Exceptions include justification, owner, and review date. +- Lead Engineer review has happened for the dependency change. + +## Policy Basis + +- [Open Source Use Policy](../software-engineering-policies/OpenSourceUse/OpenSourceUsePolicy.md) +- [Third-Party Licensing Policy](../software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingPolicy.md) +- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md) +- [Baseline Pipeline Policy](../software-engineering-policies/Pipelines/Baseline_Policy.md) +- [Managing Dependencies](../security/DependencyManagement/ManagingDependencies.md) +- [Managing Security Concerns](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) + +## Anti-Patterns + +- Pulling packages directly from unapproved sources +- Adding packages without checking licenses +- Running with dependency tooling disabled on active repositories +- Ignoring vulnerability scan failures near release +- Deferring remediation without tracked rationale and mitigations +- Suppressing vulnerabilities without an auditable rationale diff --git a/golden paths/05-document-and-hand-over-a-service.md b/golden paths/05-document-and-hand-over-a-service.md new file mode 100644 index 00000000..5daff260 --- /dev/null +++ b/golden paths/05-document-and-hand-over-a-service.md @@ -0,0 +1,52 @@ +# Golden Path: Document and Hand Over a Service + +Use this when a service is new, significantly changed, or being handed over to a +support team. + +## Outcome + +You leave behind enough accurate documentation and non-functional evidence for a +delivery or support team to run and change the service safely. + +## Steps + +1. Capture the essential system view. + Document the high-level architecture, build process, deployment approach, + configuration model, and any practical guidance needed to get productive. +2. Keep the documentation with the audience. + Store it where the delivery and support teams will naturally find and review + it. +3. Treat documentation like code. + Raise documentation changes through peer review with the implementation work. +4. Confirm non-functional requirements early. + Make sure NFRs exist at the start of the work. If they do not, involve the + solution architect. +5. Revisit NFRs during delivery. + If they evolve, update the solution and evidence rather than deprioritising + them. +6. Align with the intended support team. + Validate any support-owned operational requirements before handover. +7. Demonstrate sign-off evidence. + Handover should include proof that the relevant NFRs have been met. +8. Update the team definition of done. + Ensure documentation and NFR evidence remain part of normal delivery, not a + one-off exercise. + +## Exit Criteria + +- System documentation exists and is current. +- Documentation changes were peer reviewed. +- NFRs are identified and evidenced. +- The support team can accept the handover without missing prerequisite detail. + +## Policy Basis + +- [System Documentation Policy](../software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md) +- [NFR Policy](../software-engineering-policies/NFRs/NFRPolicy.md) +- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md) + +## Anti-Patterns + +- Treating handover documentation as an afterthought +- Keeping key run or deployment knowledge only in people’s heads +- Deferring NFR evidence until the end of delivery diff --git a/golden paths/06-handle-defects-security-and-technical-debt.md b/golden paths/06-handle-defects-security-and-technical-debt.md new file mode 100644 index 00000000..a003ee8b --- /dev/null +++ b/golden paths/06-handle-defects-security-and-technical-debt.md @@ -0,0 +1,65 @@ +# Golden Path: Handle Defects, Security Concerns and Technical Debt + +Use this when a problem is discovered in delivery or support and the team needs a +consistent route to record, prioritise, fix, or consciously carry the risk. + +## Outcome + +You create traceable records for defects, security concerns, and technical debt, +and you manage each through the correct workflow. + +## Steps + +1. Classify the issue correctly. + Decide whether it is a standard defect, a security concern, technical debt, + or a combination. +2. Log it in the team’s tracking system. + Every team must have an effective defect management workflow, and security + concerns should live in the same work tracking system. +3. Use the correct ticket shape. + Security concerns should be raised as a `Risk` with category `Security`. + Technical debt not being resolved in the current sprint should be raised as a + `Technical debt` work item. +4. Record minimum useful detail. + Include affected service, a clear description, reproduction details where + possible, stakeholders, and supporting evidence. +5. Assess and prioritise quickly. + Security concerns require an initial assessment within two working days and + should be reviewed on the team’s normal delivery cadence. +6. Fix through the normal engineering path. + Apply code review, automated testing, and pipeline checks to the remediation. +7. Retest after remediation. + If tooling or testing exposed the issue, rerun the same checks to confirm it + is resolved and nothing new has been introduced. +8. Update the record with evidence. + Add links to pull requests, test results, pipeline runs, or decisions to + accept risk. +9. Escalate when the risk is higher than routine delivery can absorb. + Work with the Security Champion, IT Security Team, and risk owner where + required. +10. Keep unresolved debt visible. + If a defect or risk is knowingly left in place, record it as technical debt + where the policy requires and keep it in the register. + +## Exit Criteria + +- The issue is logged in the correct workflow. +- Security items have an assessment and owner. +- Fixes are evidenced by normal engineering controls. +- Unresolved debt or accepted risk is explicitly recorded. + +## Policy Basis + +- [Defect Management Policy](../software-engineering-policies/DefectManagement/DefectManagementPolicy.md) +- [Managing Security Concerns](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) +- [Secure Development Policy](../software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md) +- [Technical Debt Policy](../software-engineering-policies/TechnicalDebt/TechnicalDebtPolicy.md) +- [Code Review Policy](../software-engineering-policies/CodeReview/CodeReviewPolicy.md) +- [Unit Testing Policy](../software-engineering-policies/UnitTesting/UnitTestingPolicy.md) + +## Anti-Patterns + +- Fixing production issues without creating a traceable record +- Treating security concerns as ordinary bugs with no risk assessment +- Leaving accepted debt undocumented +- Closing an issue without rerunning the check that found it diff --git a/golden paths/README.md b/golden paths/README.md new file mode 100644 index 00000000..b0c1a598 --- /dev/null +++ b/golden paths/README.md @@ -0,0 +1,28 @@ +# Golden Paths + +These guides turn the policies in this repository into concrete delivery workflows. +They are intentionally opinionated so teams can move quickly without having to +reconstruct the expected path from multiple policy pages. + +If a golden path and a policy ever disagree, the source policy wins. + +## Guides + +- [Start a new repository](01-start-a-new-repository.md) +- [Deliver a code change](02-deliver-a-code-change.md) +- [Release through a pipeline](03-release-through-a-pipeline.md) +- [Adopt or update a dependency](04-adopt-or-update-a-dependency.md) +- [Document and hand over a service](05-document-and-hand-over-a-service.md) +- [Handle defects, security concerns and technical debt](06-handle-defects-security-and-technical-debt.md) + +## Source Policies + +- [Software Engineering Policies](../software-engineering-policies/README.md) +- [Test Strategy](../quality-assurance/test-strategy.md) +- [Managing Security Concerns](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) + +## Suggested Use + +Use these documents as working agreements for teams, onboarding material for new +engineers, and a quick reference during delivery. They are written to be read in +sequence or used independently.