From 8e483f9c3bbbeaf150f774c7a7e7b5a04b10028e Mon Sep 17 00:00:00 2001 From: Martyn Fewtrell Date: Wed, 13 May 2026 16:48:05 +0100 Subject: [PATCH 1/4] Restructured site to improve navigation and user experience. --- .../quality-assurance}/README.md | 0 .../quality-assurance}/acceptance-criteria.md | 0 .../quality-assurance}/accessibility-testing.md | 0 .../quality-assurance}/ai-usage.md | 0 .../quality-assurance}/automated-api-testing.md | 0 .../quality-assurance}/bdd.md | 0 .../quality-assurance}/browser-automation.md | 0 .../desktop-accessibility-testing.md | 0 .../quality-assurance}/executable-specifications.md | 0 .../quality-assurance}/exploratory-testing.md | 0 .../quality-assurance}/http-api-mocking-tools.md | 0 .../quality-assurance}/images/bdd_tree_swing.png | Bin .../images/dicovery_formulation_automation.png | Bin .../quality-assurance}/images/example_mapping.png | Bin .../quality-assurance}/images/test-pyramid.png | Bin .../quality-assurance}/images/the_test_pyramid.png | Bin .../images/the_test_pyramid_updated.png | Bin .../quality-assurance}/images/zap2.jpg | Bin .../quality-assurance}/images/zap3.jpg | Bin .../quality-assurance}/images/zap4.jpg | Bin .../quality-assurance}/images/zap5.jpg | Bin .../quality-assurance}/images/zap6.jpg | Bin .../quality-assurance}/images/zap7.jpg | Bin .../quality-assurance}/images/zap8.jpg | Bin .../quality-assurance}/images/zapazuresetup.jpg | Bin .../quality-assurance}/manual-test-scripts.md | 0 .../quality-assurance}/microservice-testing.md | 0 .../performance-test-checklist.md | 0 .../quality-assurance}/safety-assurance-guidance.md | 0 .../quality-assurance}/test-code-standards.md | 0 .../quality-assurance}/test-policy.md | 0 .../quality-assurance}/test-repositories.md | 0 .../quality-assurance}/test-strategy.md | 0 .../quality-assurance}/ukho-quality-charter.md | 0 .../quality-assurance}/user-acceptance-testing.md | 0 .../quality-assurance}/web-accessibility-testing.md | 0 .../roles/principal-developer.md | 0 .../strategy/software-engineering-ai-strategy.md | 0 38 files changed, 0 insertions(+), 0 deletions(-) rename {quality-assurance => communities/quality-assurance}/README.md (100%) rename {quality-assurance => communities/quality-assurance}/acceptance-criteria.md (100%) rename {quality-assurance => communities/quality-assurance}/accessibility-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/ai-usage.md (100%) rename {quality-assurance => communities/quality-assurance}/automated-api-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/bdd.md (100%) rename {quality-assurance => communities/quality-assurance}/browser-automation.md (100%) rename {quality-assurance => communities/quality-assurance}/desktop-accessibility-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/executable-specifications.md (100%) rename {quality-assurance => communities/quality-assurance}/exploratory-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/http-api-mocking-tools.md (100%) rename {quality-assurance => communities/quality-assurance}/images/bdd_tree_swing.png (100%) rename {quality-assurance => communities/quality-assurance}/images/dicovery_formulation_automation.png (100%) rename {quality-assurance => communities/quality-assurance}/images/example_mapping.png (100%) rename {quality-assurance => communities/quality-assurance}/images/test-pyramid.png (100%) rename {quality-assurance => communities/quality-assurance}/images/the_test_pyramid.png (100%) rename {quality-assurance => communities/quality-assurance}/images/the_test_pyramid_updated.png (100%) rename {quality-assurance => communities/quality-assurance}/images/zap2.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap3.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap4.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap5.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap6.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap7.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zap8.jpg (100%) rename {quality-assurance => communities/quality-assurance}/images/zapazuresetup.jpg (100%) rename {quality-assurance => communities/quality-assurance}/manual-test-scripts.md (100%) rename {quality-assurance => communities/quality-assurance}/microservice-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/performance-test-checklist.md (100%) rename {quality-assurance => communities/quality-assurance}/safety-assurance-guidance.md (100%) rename {quality-assurance => communities/quality-assurance}/test-code-standards.md (100%) rename {quality-assurance => communities/quality-assurance}/test-policy.md (100%) rename {quality-assurance => communities/quality-assurance}/test-repositories.md (100%) rename {quality-assurance => communities/quality-assurance}/test-strategy.md (100%) rename {quality-assurance => communities/quality-assurance}/ukho-quality-charter.md (100%) rename {quality-assurance => communities/quality-assurance}/user-acceptance-testing.md (100%) rename {quality-assurance => communities/quality-assurance}/web-accessibility-testing.md (100%) rename {software-engineering => communities/software-engineering}/roles/principal-developer.md (100%) rename {software-engineering => communities/software-engineering}/strategy/software-engineering-ai-strategy.md (100%) diff --git a/quality-assurance/README.md b/communities/quality-assurance/README.md similarity index 100% rename from quality-assurance/README.md rename to communities/quality-assurance/README.md diff --git a/quality-assurance/acceptance-criteria.md b/communities/quality-assurance/acceptance-criteria.md similarity index 100% rename from quality-assurance/acceptance-criteria.md rename to communities/quality-assurance/acceptance-criteria.md diff --git a/quality-assurance/accessibility-testing.md b/communities/quality-assurance/accessibility-testing.md similarity index 100% rename from quality-assurance/accessibility-testing.md rename to communities/quality-assurance/accessibility-testing.md diff --git a/quality-assurance/ai-usage.md b/communities/quality-assurance/ai-usage.md similarity index 100% rename from quality-assurance/ai-usage.md rename to communities/quality-assurance/ai-usage.md diff --git a/quality-assurance/automated-api-testing.md b/communities/quality-assurance/automated-api-testing.md similarity index 100% rename from quality-assurance/automated-api-testing.md rename to communities/quality-assurance/automated-api-testing.md diff --git a/quality-assurance/bdd.md b/communities/quality-assurance/bdd.md similarity index 100% rename from quality-assurance/bdd.md rename to communities/quality-assurance/bdd.md diff --git a/quality-assurance/browser-automation.md b/communities/quality-assurance/browser-automation.md similarity index 100% rename from quality-assurance/browser-automation.md rename to communities/quality-assurance/browser-automation.md diff --git a/quality-assurance/desktop-accessibility-testing.md b/communities/quality-assurance/desktop-accessibility-testing.md similarity index 100% rename from quality-assurance/desktop-accessibility-testing.md rename to communities/quality-assurance/desktop-accessibility-testing.md diff --git a/quality-assurance/executable-specifications.md b/communities/quality-assurance/executable-specifications.md similarity index 100% rename from quality-assurance/executable-specifications.md rename to communities/quality-assurance/executable-specifications.md diff --git a/quality-assurance/exploratory-testing.md b/communities/quality-assurance/exploratory-testing.md similarity index 100% rename from quality-assurance/exploratory-testing.md rename to communities/quality-assurance/exploratory-testing.md diff --git a/quality-assurance/http-api-mocking-tools.md b/communities/quality-assurance/http-api-mocking-tools.md similarity index 100% rename from quality-assurance/http-api-mocking-tools.md rename to communities/quality-assurance/http-api-mocking-tools.md diff --git a/quality-assurance/images/bdd_tree_swing.png b/communities/quality-assurance/images/bdd_tree_swing.png similarity index 100% rename from quality-assurance/images/bdd_tree_swing.png rename to communities/quality-assurance/images/bdd_tree_swing.png diff --git a/quality-assurance/images/dicovery_formulation_automation.png b/communities/quality-assurance/images/dicovery_formulation_automation.png similarity index 100% rename from quality-assurance/images/dicovery_formulation_automation.png rename to communities/quality-assurance/images/dicovery_formulation_automation.png diff --git a/quality-assurance/images/example_mapping.png b/communities/quality-assurance/images/example_mapping.png similarity index 100% rename from quality-assurance/images/example_mapping.png rename to communities/quality-assurance/images/example_mapping.png diff --git a/quality-assurance/images/test-pyramid.png b/communities/quality-assurance/images/test-pyramid.png similarity index 100% rename from quality-assurance/images/test-pyramid.png rename to communities/quality-assurance/images/test-pyramid.png diff --git a/quality-assurance/images/the_test_pyramid.png b/communities/quality-assurance/images/the_test_pyramid.png similarity index 100% rename from quality-assurance/images/the_test_pyramid.png rename to communities/quality-assurance/images/the_test_pyramid.png diff --git a/quality-assurance/images/the_test_pyramid_updated.png b/communities/quality-assurance/images/the_test_pyramid_updated.png similarity index 100% rename from quality-assurance/images/the_test_pyramid_updated.png rename to communities/quality-assurance/images/the_test_pyramid_updated.png diff --git a/quality-assurance/images/zap2.jpg b/communities/quality-assurance/images/zap2.jpg similarity index 100% rename from quality-assurance/images/zap2.jpg rename to communities/quality-assurance/images/zap2.jpg diff --git a/quality-assurance/images/zap3.jpg b/communities/quality-assurance/images/zap3.jpg similarity index 100% rename from quality-assurance/images/zap3.jpg rename to communities/quality-assurance/images/zap3.jpg diff --git a/quality-assurance/images/zap4.jpg b/communities/quality-assurance/images/zap4.jpg similarity index 100% rename from quality-assurance/images/zap4.jpg rename to communities/quality-assurance/images/zap4.jpg diff --git a/quality-assurance/images/zap5.jpg b/communities/quality-assurance/images/zap5.jpg similarity index 100% rename from quality-assurance/images/zap5.jpg rename to communities/quality-assurance/images/zap5.jpg diff --git a/quality-assurance/images/zap6.jpg b/communities/quality-assurance/images/zap6.jpg similarity index 100% rename from quality-assurance/images/zap6.jpg rename to communities/quality-assurance/images/zap6.jpg diff --git a/quality-assurance/images/zap7.jpg b/communities/quality-assurance/images/zap7.jpg similarity index 100% rename from quality-assurance/images/zap7.jpg rename to communities/quality-assurance/images/zap7.jpg diff --git a/quality-assurance/images/zap8.jpg b/communities/quality-assurance/images/zap8.jpg similarity index 100% rename from quality-assurance/images/zap8.jpg rename to communities/quality-assurance/images/zap8.jpg diff --git a/quality-assurance/images/zapazuresetup.jpg b/communities/quality-assurance/images/zapazuresetup.jpg similarity index 100% rename from quality-assurance/images/zapazuresetup.jpg rename to communities/quality-assurance/images/zapazuresetup.jpg diff --git a/quality-assurance/manual-test-scripts.md b/communities/quality-assurance/manual-test-scripts.md similarity index 100% rename from quality-assurance/manual-test-scripts.md rename to communities/quality-assurance/manual-test-scripts.md diff --git a/quality-assurance/microservice-testing.md b/communities/quality-assurance/microservice-testing.md similarity index 100% rename from quality-assurance/microservice-testing.md rename to communities/quality-assurance/microservice-testing.md diff --git a/quality-assurance/performance-test-checklist.md b/communities/quality-assurance/performance-test-checklist.md similarity index 100% rename from quality-assurance/performance-test-checklist.md rename to communities/quality-assurance/performance-test-checklist.md diff --git a/quality-assurance/safety-assurance-guidance.md b/communities/quality-assurance/safety-assurance-guidance.md similarity index 100% rename from quality-assurance/safety-assurance-guidance.md rename to communities/quality-assurance/safety-assurance-guidance.md diff --git a/quality-assurance/test-code-standards.md b/communities/quality-assurance/test-code-standards.md similarity index 100% rename from quality-assurance/test-code-standards.md rename to communities/quality-assurance/test-code-standards.md diff --git a/quality-assurance/test-policy.md b/communities/quality-assurance/test-policy.md similarity index 100% rename from quality-assurance/test-policy.md rename to communities/quality-assurance/test-policy.md diff --git a/quality-assurance/test-repositories.md b/communities/quality-assurance/test-repositories.md similarity index 100% rename from quality-assurance/test-repositories.md rename to communities/quality-assurance/test-repositories.md diff --git a/quality-assurance/test-strategy.md b/communities/quality-assurance/test-strategy.md similarity index 100% rename from quality-assurance/test-strategy.md rename to communities/quality-assurance/test-strategy.md diff --git a/quality-assurance/ukho-quality-charter.md b/communities/quality-assurance/ukho-quality-charter.md similarity index 100% rename from quality-assurance/ukho-quality-charter.md rename to communities/quality-assurance/ukho-quality-charter.md diff --git a/quality-assurance/user-acceptance-testing.md b/communities/quality-assurance/user-acceptance-testing.md similarity index 100% rename from quality-assurance/user-acceptance-testing.md rename to communities/quality-assurance/user-acceptance-testing.md diff --git a/quality-assurance/web-accessibility-testing.md b/communities/quality-assurance/web-accessibility-testing.md similarity index 100% rename from quality-assurance/web-accessibility-testing.md rename to communities/quality-assurance/web-accessibility-testing.md diff --git a/software-engineering/roles/principal-developer.md b/communities/software-engineering/roles/principal-developer.md similarity index 100% rename from software-engineering/roles/principal-developer.md rename to communities/software-engineering/roles/principal-developer.md diff --git a/software-engineering/strategy/software-engineering-ai-strategy.md b/communities/software-engineering/strategy/software-engineering-ai-strategy.md similarity index 100% rename from software-engineering/strategy/software-engineering-ai-strategy.md rename to communities/software-engineering/strategy/software-engineering-ai-strategy.md From d13206605c8dc867835734030bc8d5781a48b9f8 Mon Sep 17 00:00:00 2001 From: Martyn Fewtrell Date: Wed, 13 May 2026 16:48:40 +0100 Subject: [PATCH 2/4] Restuctured to improve navigation and user experience --- CONTRIBUTING.md | 47 ++++++- README.md | 131 ++++++++++++++++-- communities/README.md | 10 ++ communities/data-engineering/README.md | 21 +++ communities/quality-assurance/README.md | 22 ++- communities/quality-assurance/ai-usage.md | 2 +- .../http-api-mocking-tools.md | 6 +- .../safety-assurance-guidance.md | 2 +- .../security-testing-guidance.md | 0 .../test-approach-tsr-reviews.md | 0 communities/security/README.md | 22 +++ .../security/cvss-scoring-metrics.md | 0 .../security/managing-security-concerns.md | 0 .../security-champion-responsibilities.md | 0 .../security/threat-modelling.md | 0 communities/software-engineering/README.md | 22 +++ .../software-engineering-ai-strategy.md | 2 +- guidance/README.md | 10 ++ guidance/checklists/README.md | 9 ++ guidance/examples/README.md | 8 ++ guidance/how-to/README.md | 9 ++ .../how-to/cloud-development}/CloudFirst.md | 0 .../how-to/cloud-development}/Containers.md | 0 .../how-to/cloud-development}/DataUse.md | 0 .../how-to/cloud-development}/Deployment.md | 2 +- .../DisasterRecoveryBusinessContinuity.md | 0 .../how-to/cloud-development}/General.md | 0 .../LoggingAndMonitoring.md | 2 +- .../cloud-development}/PilotsLicense.md | 0 .../how-to/cloud-development}/README.md | 12 +- .../how-to/cloud-development}/Tagging.md | 0 .../how-to/cloud-development}/Users.md | 0 ...een-anonymization-and-pseudonymization.png | Bin guidance/how-to/github/README.md | 54 ++++++++ .../github}/creating-a-contributing-file.md | 0 .../how-to/github}/creating-a-readme-file.md | 0 .../how-to/github}/migrating-to-github.md | 2 +- .../how-to/github}/pull-request-details.md | 0 .../induction}/LeadDeveloperInduction.md | 0 guidance/how-to/induction/README.md | 6 + .../how-to/induction}/SettingUpYourMSDN.md | 0 .../how-to/infrastructure-as-code/README.md | 9 ++ .../infrastructure-as-code}/terraform.md | 0 .../GuidanceForLoggingToElasticCloud.md | 0 .../how-to/logging}/LoggingPolicy.md | 0 guidance/how-to/logging/README.md | 10 ++ guidance/playbooks/README.md | 5 + .../PackageAdoptionChecklist.md | 0 .../PackageAdoptionGuidance.md | 0 .../PackageAdoptionPolicy.md | 2 +- guidance/playbooks/package-adoption/README.md | 11 ++ policies/README.md | 11 ++ policies/data/README.md | 9 ++ policies/engineering/README.md | 20 +++ .../code-copyright}/CodeCopyrightPolicy.md | 2 +- .../CodeGenerationToolsPolicy.md | 0 .../code-reuse}/CodeReusePolicy.md | 0 .../code-review}/CodeReviewPolicy.md | 0 .../engineering/front-end}/FrontEndPolicy.md | 0 .../InclusiveLanguagePolicy.md | 0 .../non-functional-requirements}/NFRPolicy.md | 0 .../PairProgrammingPolicy.md | 0 .../technical-debt}/Example_TD_V4.png | Bin .../technical-debt}/Porfolio_TD_V1.png | Bin .../TechnicalDebtMonitoring.md | 0 .../technical-debt}/TechnicalDebtPolicy.md | 0 .../technical-debt}/dashboard_TD_V1.png | Bin policies/platform/README.md | 16 +++ .../containers}/ContainerBestPractices.md | 0 .../platform/containers}/ContainerPolicy.md | 0 .../OpenSourceContributionPolicy.md | 0 .../OpenSourceGovernanceChecklist.md | 0 .../open-source-use}/OpenSourceUsePolicy.md | 0 .../platform/pipelines/baseline-policy.md | 0 .../ThirdPartyLicensingGuidance.md | 0 .../ThirdPartyLicensingPolicy.md | 0 policies/security/README.md | 12 ++ .../SecureDevelopmentPolicy.md | 8 +- policies/testing/README.md | 13 ++ .../DefectManagementPolicy.md | 0 .../unit-testing}/UnitTestingPolicy.md | 0 reference/README.md | 9 ++ reference/roles/README.md | 10 ++ .../roles}/engineering-team.md | 0 .../roles/principal-developer.md | 0 reference/technology-radar/README.md | 8 ++ .../technology-radar/public-radar.csv | 0 .../TechnologyGovernance.md | 0 reference/templates/README.md | 10 ++ .../templates/resources}/baseline-diagram.png | Bin .../templates/resources}/control-options.png | Bin software-engineering-policies/CONTRIBUTING.md | 26 ---- software-engineering-policies/README.md | 24 ---- standards/README.md | 11 ++ standards/coding/README.md | 9 ++ .../coding-standards}/CssCodingStandards.md | 0 .../DotNetCodingStandards.md | 0 .../coding-standards}/HtmlCodingStandards.md | 0 .../JavascriptCodingStandards.md | 0 .../PythonCodingStandards.md | 0 .../coding/coding-standards}/README.md | 0 standards/documentation/README.md | 12 ++ .../documentation}/development-principles.md | 0 .../naming-conventions}/NamingConventions.md | 0 .../SystemDocumentationPolicy.md | 0 standards/observability/README.md | 10 ++ .../observability/observability-policy.md | 0 standards/source-control/README.md | 13 ++ .../source-control}/AzDoBranchProtection.md | 0 .../GitBranchProtectionPolicy.md | 0 .../source-control}/RepositorySetupPolicy.md | 4 +- .../source-control}/SourceControlPolicy.md | 4 +- standards/testing/README.md | 8 ++ using-github/readme.md | 51 ------- 114 files changed, 603 insertions(+), 135 deletions(-) create mode 100644 communities/README.md create mode 100644 communities/data-engineering/README.md rename quality-assurance/Security-Testing-Guidance.md => communities/quality-assurance/security-testing-guidance.md (100%) rename quality-assurance/Test-Approach-TSR-Reviews.md => communities/quality-assurance/test-approach-tsr-reviews.md (100%) create mode 100644 communities/security/README.md rename security/ManagingSecurityConcerns/CvssScoringMetrics.md => communities/security/cvss-scoring-metrics.md (100%) rename security/ManagingSecurityConcerns/ManagingSecurityConcerns.md => communities/security/managing-security-concerns.md (100%) rename security/SecurityChampions/SecurityChampionResponsibilities.md => communities/security/security-champion-responsibilities.md (100%) rename security/ThreatModelling/ThreatModelling.md => communities/security/threat-modelling.md (100%) create mode 100644 communities/software-engineering/README.md create mode 100644 guidance/README.md create mode 100644 guidance/checklists/README.md create mode 100644 guidance/examples/README.md create mode 100644 guidance/how-to/README.md rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/CloudFirst.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/Containers.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/DataUse.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/Deployment.md (97%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/DisasterRecoveryBusinessContinuity.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/General.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/LoggingAndMonitoring.md (77%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/PilotsLicense.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/README.md (81%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/Tagging.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/Users.md (100%) rename {software-engineering-policies/CloudDevelopment => guidance/how-to/cloud-development}/images/Difference-between-anonymization-and-pseudonymization.png (100%) create mode 100644 guidance/how-to/github/README.md rename {using-github => guidance/how-to/github}/creating-a-contributing-file.md (100%) rename {using-github => guidance/how-to/github}/creating-a-readme-file.md (100%) rename {using-github => guidance/how-to/github}/migrating-to-github.md (64%) rename {using-github => guidance/how-to/github}/pull-request-details.md (100%) rename {software-engineering-policies/Induction => guidance/how-to/induction}/LeadDeveloperInduction.md (100%) create mode 100644 guidance/how-to/induction/README.md rename {software-engineering-policies/Induction => guidance/how-to/induction}/SettingUpYourMSDN.md (100%) create mode 100644 guidance/how-to/infrastructure-as-code/README.md rename {software-engineering-policies/InfrastructureAsCode => guidance/how-to/infrastructure-as-code}/terraform.md (100%) rename {software-engineering-policies/Logging => guidance/how-to/logging}/GuidanceForLoggingToElasticCloud.md (100%) rename {software-engineering-policies/Logging => guidance/how-to/logging}/LoggingPolicy.md (100%) create mode 100644 guidance/how-to/logging/README.md create mode 100644 guidance/playbooks/README.md rename {software-engineering-policies/PackageAdoption => guidance/playbooks/package-adoption}/PackageAdoptionChecklist.md (100%) rename {software-engineering-policies/PackageAdoption => guidance/playbooks/package-adoption}/PackageAdoptionGuidance.md (100%) rename {software-engineering-policies/PackageAdoption => guidance/playbooks/package-adoption}/PackageAdoptionPolicy.md (62%) create mode 100644 guidance/playbooks/package-adoption/README.md create mode 100644 policies/README.md create mode 100644 policies/data/README.md create mode 100644 policies/engineering/README.md rename {software-engineering-policies/CodeCopyright => policies/engineering/code-copyright}/CodeCopyrightPolicy.md (79%) rename {software-engineering-policies/CodeGenerationTools => policies/engineering/code-generation-tools}/CodeGenerationToolsPolicy.md (100%) rename {software-engineering-policies/CodeReuse => policies/engineering/code-reuse}/CodeReusePolicy.md (100%) rename {software-engineering-policies/CodeReview => policies/engineering/code-review}/CodeReviewPolicy.md (100%) rename {software-engineering-policies/FrontEnd => policies/engineering/front-end}/FrontEndPolicy.md (100%) rename {software-engineering-policies/InclusiveLanguage => policies/engineering/inclusive-language}/InclusiveLanguagePolicy.md (100%) rename {software-engineering-policies/NFRs => policies/engineering/non-functional-requirements}/NFRPolicy.md (100%) rename {software-engineering-policies/PairProgramming => policies/engineering/pair-programming}/PairProgrammingPolicy.md (100%) rename {software-engineering-policies/TechnicalDebt => policies/engineering/technical-debt}/Example_TD_V4.png (100%) rename {software-engineering-policies/TechnicalDebt => policies/engineering/technical-debt}/Porfolio_TD_V1.png (100%) rename {software-engineering-policies/TechnicalDebt => policies/engineering/technical-debt}/TechnicalDebtMonitoring.md (100%) rename {software-engineering-policies/TechnicalDebt => policies/engineering/technical-debt}/TechnicalDebtPolicy.md (100%) rename {software-engineering-policies/TechnicalDebt => policies/engineering/technical-debt}/dashboard_TD_V1.png (100%) create mode 100644 policies/platform/README.md rename {software-engineering-policies/Containers => policies/platform/containers}/ContainerBestPractices.md (100%) rename {software-engineering-policies/Containers => policies/platform/containers}/ContainerPolicy.md (100%) rename {software-engineering-policies/OpenSourceContribution => policies/platform/open-source-contribution}/OpenSourceContributionPolicy.md (100%) rename {software-engineering-policies/OpenSourceContribution => policies/platform/open-source-contribution}/OpenSourceGovernanceChecklist.md (100%) rename {software-engineering-policies/OpenSourceUse => policies/platform/open-source-use}/OpenSourceUsePolicy.md (100%) rename software-engineering-policies/Pipelines/Baseline_Policy.md => policies/platform/pipelines/baseline-policy.md (100%) rename {software-engineering-policies/ThirdPartyLicensing => policies/platform/third-party-licensing}/ThirdPartyLicensingGuidance.md (100%) rename {software-engineering-policies/ThirdPartyLicensing => policies/platform/third-party-licensing}/ThirdPartyLicensingPolicy.md (100%) create mode 100644 policies/security/README.md rename {software-engineering-policies/SecureDevelopment => policies/security/secure-development}/SecureDevelopmentPolicy.md (94%) create mode 100644 policies/testing/README.md rename {software-engineering-policies/DefectManagement => policies/testing/defect-management}/DefectManagementPolicy.md (100%) rename {software-engineering-policies/UnitTesting => policies/testing/unit-testing}/UnitTestingPolicy.md (100%) create mode 100644 reference/README.md create mode 100644 reference/roles/README.md rename {software-engineering-policies => reference/roles}/engineering-team.md (100%) rename {communities/software-engineering => reference}/roles/principal-developer.md (100%) create mode 100644 reference/technology-radar/README.md rename software-engineering-policies/PublicRadar.csv => reference/technology-radar/public-radar.csv (100%) rename {software-engineering-policies/TechnologyGovernance => reference/technology-radar/technology-governance}/TechnologyGovernance.md (100%) create mode 100644 reference/templates/README.md rename {software-engineering-policies/Resources => reference/templates/resources}/baseline-diagram.png (100%) rename {software-engineering-policies/Resources => reference/templates/resources}/control-options.png (100%) delete mode 100644 software-engineering-policies/CONTRIBUTING.md delete mode 100644 software-engineering-policies/README.md create mode 100644 standards/README.md create mode 100644 standards/coding/README.md rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/CssCodingStandards.md (100%) rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/DotNetCodingStandards.md (100%) rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/HtmlCodingStandards.md (100%) rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/JavascriptCodingStandards.md (100%) rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/PythonCodingStandards.md (100%) rename {software-engineering-policies/CodingStandards => standards/coding/coding-standards}/README.md (100%) create mode 100644 standards/documentation/README.md rename {software-engineering-policies => standards/documentation}/development-principles.md (100%) rename {software-engineering-policies/NamingConventions => standards/documentation/naming-conventions}/NamingConventions.md (100%) rename {software-engineering-policies/SystemDocumentation => standards/documentation/system-documentation}/SystemDocumentationPolicy.md (100%) create mode 100644 standards/observability/README.md rename software-engineering-policies/Observability/observability_policy.md => standards/observability/observability/observability-policy.md (100%) create mode 100644 standards/source-control/README.md rename {software-engineering-policies/SourceControl => standards/source-control/source-control}/AzDoBranchProtection.md (100%) rename {software-engineering-policies/SourceControl => standards/source-control/source-control}/GitBranchProtectionPolicy.md (100%) rename {software-engineering-policies/SourceControl => standards/source-control/source-control}/RepositorySetupPolicy.md (92%) rename {software-engineering-policies/SourceControl => standards/source-control/source-control}/SourceControlPolicy.md (93%) create mode 100644 standards/testing/README.md delete mode 100644 using-github/readme.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4d742c3fa..26c4d03b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,54 @@ # Contributing to UKHO Docs -Firstly, thank you for taking the time to contribute! We appreciate it as this is not the most exciting or glamorous of topics. +Firstly, thank you for taking the time to contribute! These are only guidelines for contributing to this repo, not hard rules. They may not fit all scenarios encountered, so please use your best judgment and feel free to propose a change to this document via a pull request if you think it can be improved. +## Repository structure + +This repository is organised by reader intent first, then by subject area. + +- `communities/` contains audience and practice entry points. +- `policies/` contains mandatory policy statements. +- `standards/` contains implementation expectations and standards. +- `guidance/` contains how-to material, playbooks, checklists, and examples. +- `reference/` contains supporting roles, templates, radar material, and similar background information. + +Before adding a new document, decide what kind of document it is and place it in the correct destination folder rather than the nearest legacy location. + +## Document types + +- **Policy**: what must be done. +- **Standard**: how mandatory requirements should be implemented. +- **Guidance**: recommended approaches and explanation. +- **Checklist**: repeatable review or assurance steps. +- **Reference**: supporting information, templates, examples, or background material. + +## Naming rules + +- folders use `kebab-case` +- markdown files use `kebab-case.md` +- readme files use `README.md` + +Avoid spaces, underscores, and mixed casing in new file and folder names. + +## Navigation updates + +When you add, move, or remove documentation: + +- update the relevant local `README.md` file +- update the root `README.md` if the change affects top-level navigation or audience journeys +- add cross-links to related areas where they materially improve discoverability +- prefer moving or linking content instead of duplicating it + +## Data-related content + +If the material is primarily about data lifecycle, retention, test data, or related assurance concerns: + +- start from `communities/data-engineering/` +- place mandatory requirements in `policies/data/` +- place practical advice in the appropriate area under `guidance/` + ## Questions If you have any questions, please open an issue. diff --git a/README.md b/README.md index 94c88c5c9..963dc96d4 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,140 @@ # Software Engineering at the UKHO -This repository contains documentation about digital delivery teams, their behaviours and processes and our engineers at the UKHO. +This repository contains documentation about digital delivery teams, their behaviours and processes, and our engineers at the UKHO. -We have eight software engineering teams that develop and support software using .Net, Java, Python and other languages. Our [tech radar](https://radar.thoughtworks.com/?sheetId=https://raw.githubusercontent.com/UKHO/docs/main/software-engineering-policies/PublicRadar.csv) (external link to thoughtworks.com) contains some more details on what we use. +We have eight software engineering teams that develop and support software using .NET, Java, Python, and other languages. Our [technology radar](./reference/technology-radar/README.md) contains more detail on the tools and approaches we use. -We’re proud that we’ve created this group by recruiting people who share a commitment to professional development and watched them grow with us. Right now, we have people pursuing certification in Azure, AWS, Kubernetes and Security; we have others on management training courses; we even have people on Masters Degree programmes. +We’re proud that we’ve created this group by recruiting people who share a commitment to professional development and watched them grow with us. Right now, we have people pursuing certification in Azure, AWS, Kubernetes, and Security; we have others on management training courses; we even have people on Masters degree programmes. + +## Start here + +Use this README as the main content map for the repository. + +- If you want community-led entry points, start in [communities](./communities/README.md). +- If you need mandatory requirements, go to [policies](./policies/README.md). +- If you need implementation expectations, go to [standards](./standards/README.md). +- If you need practical advice, playbooks, or checklists, go to [guidance](./guidance/README.md). +- If you need supporting roles, templates, or radar material, go to [reference](./reference/README.md). + +## Repository structure overview + +```text +/ +├── README.md +├── communities/ +├── policies/ +├── standards/ +├── guidance/ +└── reference/ +``` + +### Communities + +- [Quality assurance](./communities/quality-assurance/README.md) +- [Security](./communities/security/README.md) +- [Software engineering](./communities/software-engineering/README.md) +- [Data engineering](./communities/data-engineering/README.md) + +### Policies + +- [Engineering policies](./policies/engineering/README.md) +- [Security policies](./policies/security/README.md) +- [Testing policies](./policies/testing/README.md) +- [Data policies](./policies/data/README.md) +- [Platform policies](./policies/platform/README.md) + +### Standards + +- [Coding standards](./standards/coding/README.md) +- [Testing standards](./standards/testing/README.md) +- [Source control standards](./standards/source-control/README.md) +- [Observability standards](./standards/observability/README.md) +- [Documentation standards](./standards/documentation/README.md) + +### Guidance + +- [How-to guidance](./guidance/how-to/README.md) +- [Playbooks](./guidance/playbooks/README.md) +- [Checklists](./guidance/checklists/README.md) +- [Examples](./guidance/examples/README.md) + +### Reference + +- [Roles](./reference/roles/README.md) +- [Technology radar](./reference/technology-radar/README.md) +- [Templates and supporting assets](./reference/templates/README.md) + +## Audience journeys + +### New starter in engineering + +1. Read [Software engineering](./communities/software-engineering/README.md). +2. Review [Engineering policies](./policies/engineering/README.md). +3. Review [Coding standards](./standards/coding/README.md). + +### Developer implementing a feature + +1. Start with [Engineering policies](./policies/engineering/README.md). +2. Review [Secure development](./policies/security/secure-development/SecureDevelopmentPolicy.md). +3. Use [Coding standards](./standards/coding/README.md) and [Source control standards](./standards/source-control/README.md). +4. Use [Cloud development guidance](./guidance/how-to/cloud-development/README.md) and [GitHub guidance](./guidance/how-to/github/README.md) where relevant. + +### Tester planning test coverage + +1. Start with [Quality assurance](./communities/quality-assurance/README.md). +2. Review [Testing policies](./policies/testing/README.md). +3. Use [Testing standards](./standards/testing/README.md). + +### Test lead reviewing assurance + +1. Start with [Quality assurance](./communities/quality-assurance/README.md). +2. Review [Test strategy](./communities/quality-assurance/test-strategy.md). +3. Review [Defect management](./policies/testing/defect-management/DefectManagementPolicy.md). + +### Security champion reviewing delivery risks + +1. Start with [Security](./communities/security/README.md). +2. Review [Secure development](./policies/security/secure-development/SecureDevelopmentPolicy.md). +3. Review [Managing security concerns](./communities/security/managing-security-concerns.md). + +### Delivery manager checking team practices + +1. Start with [Software engineering](./communities/software-engineering/README.md). +2. Review [Platform policies](./policies/platform/README.md). +3. Review [Reference roles](./reference/roles/README.md). + +### Data practitioner handling data-related concerns + +1. Start with [Data engineering](./communities/data-engineering/README.md). +2. Review [Data policies](./policies/data/README.md). +3. Use [Cloud development guidance](./guidance/how-to/cloud-development/README.md), especially [Data use in the cloud](./guidance/how-to/cloud-development/DataUse.md). + +### Contributor proposing a policy update + +1. Read [CONTRIBUTING.md](./CONTRIBUTING.md). +2. Use the area index for the document type you are changing. +3. Update the relevant local `README.md` files when you add or move material. ## How we work -Everything we do is team based. We take Agile seriously; your delivery team will be small but will have the people it needs to get things done - developers, testers, a product owner and a delivery manager - as well as access to infrastructure specialists, UX experts and analysts. +Everything we do is team based. We take Agile seriously; your delivery team will be small but will have the people it needs to get things done - developers, testers, a product owner, and a delivery manager - as well as access to infrastructure specialists, UX experts, and analysts. -Quality is paramount. Our [engineering](./software-engineering-policies/README.md) and [quality assurance](./quality-assurance/README.md) policies support our teams to do good work. Most code is done [in pairs](./software-engineering-policies/PairProgramming/PairProgrammingPolicy.md) or larger groups to ensure quality and to spread knowledge. Everyone [reviews code](./software-engineering-policies/CodeReview/CodeReviewPolicy.md) and everyone welcomes feedback. +Quality is paramount. Our [engineering policies](./policies/engineering/README.md) and [quality assurance community guidance](./communities/quality-assurance/README.md) support our teams to do good work. Most code is done [in pairs](./policies/engineering/pair-programming/PairProgrammingPolicy.md) or larger groups to ensure quality and to spread knowledge. Everyone [reviews code](./policies/engineering/code-review/CodeReviewPolicy.md) and everyone welcomes feedback. -We strive to automate as much as possible: [testing](./quality-assurance/test-strategy.md), builds, deployments use the latest automation tools available. +We strive to automate as much as possible: [testing](./communities/quality-assurance/test-strategy.md), builds, and deployments use the latest automation tools available. -We actively look to pay down [technical debt](./software-engineering-policies/TechnicalDebt/TechnicalDebtGuidance.md). +We actively look to pay down [technical debt](./policies/engineering/technical-debt/TechnicalDebtMonitoring.md). ## Our community We encourage the formation of specialist communities to support our interests and our work. -The community of Lead Developers provides technical leadership, recommending tools, technologies and techniques for adoption. This group contains people with various specialisms and levels of experience who all support each other in their roles. +The community of Lead Developers provides technical leadership, recommending tools, technologies, and techniques for adoption. This group contains people with various specialisms and levels of experience who all support each other in their roles. -Our [Security Champion](./security/SecurityChampions/SecurityChampionResponsibilities.md) community is made up of people interested in [application security](./software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md), and coaches teams to create safer software, as well as increasing their own skills and qualifications. +Our [Security Champion](./communities/security/security-champion-responsibilities.md) community is made up of people interested in [application security](./policies/security/secure-development/SecureDevelopmentPolicy.md), and coaches teams to create safer software, as well as increasing their own skills and qualifications. -We also have many other communities of interest covering such things as Accessibility, Testing, UX, Azure, AWS and .Net. +We also have many other communities of interest covering such things as accessibility, testing, UX, Azure, AWS, and .NET. ## Balance -We offer a great work / life balance - start and end times are fluid, centred around a 10am – 2pm team time, where the team is focussed on building things (no meetings!). We’re all set up for working from home and encourage people to make use of this if they prefer. We are committed to providing part-time options and offer reasonable accommodations to help people meet their needs. +We offer a great work / life balance - start and end times are fluid, centred around a 10am – 2pm team time, where the team is focussed on building things (no meetings). We’re all set up for working from home and encourage people to make use of this if they prefer. We are committed to providing part-time options and offer reasonable accommodations to help people meet their needs. diff --git a/communities/README.md b/communities/README.md new file mode 100644 index 000000000..67a008af6 --- /dev/null +++ b/communities/README.md @@ -0,0 +1,10 @@ +# Communities + +Use the communities area when you want entry points organised by audience, practice, or owning community. + +## Areas + +- [Quality assurance](./quality-assurance/README.md) +- [Security](./security/README.md) +- [Software engineering](./software-engineering/README.md) +- [Data engineering](./data-engineering/README.md) diff --git a/communities/data-engineering/README.md b/communities/data-engineering/README.md new file mode 100644 index 000000000..9f298aeca --- /dev/null +++ b/communities/data-engineering/README.md @@ -0,0 +1,21 @@ +# Data engineering + +This area is the first-class entry point for data-related guidance in the repository. + +## Intended audience + +- data practitioners +- engineers handling data lifecycle concerns +- delivery teams working with test data, retention, and security requirements + +## Start here + +- [Data use in the cloud](../../guidance/how-to/cloud-development/DataUse.md) +- [Cloud development guidance](../../guidance/how-to/cloud-development/README.md) +- [Security community](../security/README.md) + +## Related areas + +- [Data policies](../../policies/data/README.md) +- [Testing policies](../../policies/testing/README.md) +- [Security policies](../../policies/security/README.md) diff --git a/communities/quality-assurance/README.md b/communities/quality-assurance/README.md index 5b1127aa3..d487eee3f 100644 --- a/communities/quality-assurance/README.md +++ b/communities/quality-assurance/README.md @@ -4,12 +4,25 @@ Welcome to Quality Assurance at the UKHO. Here you will find both process and te This is a community site - if you want to add or change a thing then submit a PR and ask a Test Lead to approve. +## Purpose + +This area is the community entry point for testing and assurance guidance. + +## Intended audience + +- testers planning and delivering assurance +- developers who need testing guidance +- test leads reviewing quality practices +- delivery teams improving test automation and coverage + ## Where to start If you read nothing else, then read these things: * Our [Test Strategy](test-strategy.md) contains details of the UKHO approach to testing. * The [UKHO Delivery Quality Charter](ukho-quality-charter.md) assists delivery teams in adopting practices proven to improve quality of delivery. +* The [Testing policies](../../policies/testing/README.md) explain the mandatory testing requirements. +* The [Testing standards](../../standards/testing/README.md) explain testing-specific implementation expectations. ## Contents @@ -25,4 +38,11 @@ If you read nothing else, then read these things: * [Performance testing checklist](performance-test-checklist.md) * [Safety assurance](safety-assurance-guidance.md) * [UI automation](browser-automation.md) - * [Security testing Guidance](Security-Testing-Guidance.md) + * [Security testing guidance](security-testing-guidance.md) + +## Related areas + +- [Security community](../security/README.md) +- [Testing policies](../../policies/testing/README.md) +- [Testing standards](../../standards/testing/README.md) +- [Guidance checklists](../../guidance/checklists/README.md) diff --git a/communities/quality-assurance/ai-usage.md b/communities/quality-assurance/ai-usage.md index 63addcb67..207aae6c1 100644 --- a/communities/quality-assurance/ai-usage.md +++ b/communities/quality-assurance/ai-usage.md @@ -4,7 +4,7 @@ This document describes the policy for the usage of AI tools in software testing ## Policy -- This policy should be used in conjunction with our policy on [AI code generation tools]([url](https://github.com/UKHO/docs/blob/main/software-engineering-policies/CodeGenerationTools/CodeGenerationToolsPolicy.md)) +- This policy should be used in conjunction with our policy on [AI code generation tools](../../policies/engineering/code-generation-tools/CodeGenerationToolsPolicy.md) - Only AI tools already approved for use can be used. Approved corporate AI tools can be used, in addition to any approved through the standard tech radar governance process. - Documents classified as Official can be used with AI - DO NOT USE any documents with a classification higher than official with AI tools diff --git a/communities/quality-assurance/http-api-mocking-tools.md b/communities/quality-assurance/http-api-mocking-tools.md index 7f2139ed5..c1daa228d 100644 --- a/communities/quality-assurance/http-api-mocking-tools.md +++ b/communities/quality-assurance/http-api-mocking-tools.md @@ -20,10 +20,10 @@ Many simple HTTP endpoint mocking problems are solved using WireMock. Parsing re WireMock stubs can run standalone and be deployed as continuously running services (e.g. to azure as a container instance/app or web app). ->When using containers refer to the [container policy](/software-engineering-policies/Containers/ContainerPolicy.md). +>When using containers refer to the [container policy](/policies/platform/containers/ContainerPolicy.md). WireMock can also be instantiated inline from code or scripts on demand and disposed after a test (e.g. locally or on build/release/test agents). ->**The .net version of WireMock is independent from the Java (wiremock.org) version. See the [open source use policy](/software-engineering-policies/OpenSourceUse/OpenSourceUsePolicy.md) when assessing the stuitability of open source software. The .net version should be used for .net projects, as the two versions are not fully compatible.** +>**The .net version of WireMock is independent from the Java (wiremock.org) version. See the [open source use policy](/policies/platform/open-source-use/OpenSourceUsePolicy.md) when assessing the suitability of open source software. The .net version should be used for .NET projects, as the two versions are not fully compatible.** ### Examples @@ -53,4 +53,4 @@ Use WireMock wherever possible for creating HTTP API mocks _unless_ your require - Are beyond fixed or templated HTTP responses and callbacks (including to other URIs) and basic unhappy path tests, most of which WireMock can cover. - Would make a WireMock based solution more effort or complexity than creating a bespoke mock. -If a mock requires complexity outside of what WireMock can facilitate, _only_ then build it using known general purpose tools (e.g. in C# using .net), keeping in line with the [software engineering policies](/software-engineering-policies). +If a mock requires complexity outside of what WireMock can facilitate, _only_ then build it using known general purpose tools (e.g. in C# using .NET), keeping in line with the [software engineering policies](/policies/README.md). diff --git a/communities/quality-assurance/safety-assurance-guidance.md b/communities/quality-assurance/safety-assurance-guidance.md index aa431febe..3d90bab5f 100644 --- a/communities/quality-assurance/safety-assurance-guidance.md +++ b/communities/quality-assurance/safety-assurance-guidance.md @@ -53,5 +53,5 @@ For more information on Safety assurance guidance, please speak to a memeber of ## Safety Debt -A team team may discover, in an existing system, improvements that can be made to its safety qualities. These are a form of technical debt which, with the agreement of the Product Owner, should be recorded in usual way as a PBI as per our [standard guidance](https://github.com/UKHO/docs/blob/main/software-engineering-policies/TechnicalDebt/TechnicalDebtGuidance.md). As well as the standard technical debt tags (*Technical Debt* and *T1/T2/T3/T4)*, the PBI should have the tag *Safety*. +A team team may discover, in an existing system, improvements that can be made to its safety qualities. These are a form of technical debt which, with the agreement of the Product Owner, should be recorded in the usual way as a PBI as per our [technical debt guidance](../../policies/engineering/technical-debt/TechnicalDebtMonitoring.md). As well as the standard technical debt tags (*Technical Debt* and *T1/T2/T3/T4)*, the PBI should have the tag *Safety*. diff --git a/quality-assurance/Security-Testing-Guidance.md b/communities/quality-assurance/security-testing-guidance.md similarity index 100% rename from quality-assurance/Security-Testing-Guidance.md rename to communities/quality-assurance/security-testing-guidance.md diff --git a/quality-assurance/Test-Approach-TSR-Reviews.md b/communities/quality-assurance/test-approach-tsr-reviews.md similarity index 100% rename from quality-assurance/Test-Approach-TSR-Reviews.md rename to communities/quality-assurance/test-approach-tsr-reviews.md diff --git a/communities/security/README.md b/communities/security/README.md new file mode 100644 index 000000000..070d12c07 --- /dev/null +++ b/communities/security/README.md @@ -0,0 +1,22 @@ +# Security + +This area is the community entry point for security-focused guidance and practices. + +## Intended audience + +- security champions +- developers building secure software +- delivery teams reviewing security risks + +## Start here + +- [Security champion responsibilities](./security-champion-responsibilities.md) +- [Managing security concerns](./managing-security-concerns.md) +- [CVSS scoring metrics](./cvss-scoring-metrics.md) +- [Threat modelling](./threat-modelling.md) + +## Related areas + +- [Secure development policy](../../policies/security/secure-development/SecureDevelopmentPolicy.md) +- [Quality assurance](../quality-assurance/README.md) +- [Data engineering](../data-engineering/README.md) diff --git a/security/ManagingSecurityConcerns/CvssScoringMetrics.md b/communities/security/cvss-scoring-metrics.md similarity index 100% rename from security/ManagingSecurityConcerns/CvssScoringMetrics.md rename to communities/security/cvss-scoring-metrics.md diff --git a/security/ManagingSecurityConcerns/ManagingSecurityConcerns.md b/communities/security/managing-security-concerns.md similarity index 100% rename from security/ManagingSecurityConcerns/ManagingSecurityConcerns.md rename to communities/security/managing-security-concerns.md diff --git a/security/SecurityChampions/SecurityChampionResponsibilities.md b/communities/security/security-champion-responsibilities.md similarity index 100% rename from security/SecurityChampions/SecurityChampionResponsibilities.md rename to communities/security/security-champion-responsibilities.md diff --git a/security/ThreatModelling/ThreatModelling.md b/communities/security/threat-modelling.md similarity index 100% rename from security/ThreatModelling/ThreatModelling.md rename to communities/security/threat-modelling.md diff --git a/communities/software-engineering/README.md b/communities/software-engineering/README.md new file mode 100644 index 000000000..01d6e8696 --- /dev/null +++ b/communities/software-engineering/README.md @@ -0,0 +1,22 @@ +# Software engineering + +This area is the community entry point for software engineering roles, strategy, and shared ways of working. + +## Intended audience + +- developers +- engineering leaders +- delivery managers +- contributors shaping engineering practice + +## Start here + +- [Software engineering AI strategy](./strategy/software-engineering-ai-strategy.md) +- [Principal developer role](../../reference/roles/principal-developer.md) +- [Engineering team reference](../../reference/roles/engineering-team.md) + +## Related areas + +- [Engineering policies](../../policies/engineering/README.md) +- [Coding standards](../../standards/coding/README.md) +- [Source control standards](../../standards/source-control/README.md) diff --git a/communities/software-engineering/strategy/software-engineering-ai-strategy.md b/communities/software-engineering/strategy/software-engineering-ai-strategy.md index 2b972c6f4..636f43fa1 100644 --- a/communities/software-engineering/strategy/software-engineering-ai-strategy.md +++ b/communities/software-engineering/strategy/software-engineering-ai-strategy.md @@ -46,7 +46,7 @@ Relationship to organisational strategy This strategy aligns with the UKHO AI strategy and Data Strategy and supports cross-departmental interoperability, auditability and assurance. It complements existing security, accessibility and procurement policies and provides actionable controls for safe developer-facing AI adoption. -Refer to the [Code Generation Tools Policy](../../software-engineering-policies/CodeGenerationTools/CodeGenerationToolsPolicy.md) for detailed organisational requirements on the use of code generation and AI-assisted development tools. +Refer to the [Code Generation Tools Policy](../../../policies/engineering/code-generation-tools/CodeGenerationToolsPolicy.md) for detailed organisational requirements on the use of code generation and AI-assisted development tools. ## 3. Principles diff --git a/guidance/README.md b/guidance/README.md new file mode 100644 index 000000000..13b2b3870 --- /dev/null +++ b/guidance/README.md @@ -0,0 +1,10 @@ +# Guidance + +Use the guidance area for practical how-to material, playbooks, checklists, and examples. + +## Areas + +- [How-to](./how-to/README.md) +- [Playbooks](./playbooks/README.md) +- [Checklists](./checklists/README.md) +- [Examples](./examples/README.md) diff --git a/guidance/checklists/README.md b/guidance/checklists/README.md new file mode 100644 index 000000000..ce3a06861 --- /dev/null +++ b/guidance/checklists/README.md @@ -0,0 +1,9 @@ +# Checklists + +This area collects repeatable review and assurance checklists. + +## Current entry points + +- [Performance test checklist](../../communities/quality-assurance/performance-test-checklist.md) +- [Open source governance checklist](../../policies/platform/open-source-contribution/OpenSourceGovernanceChecklist.md) +- [Package adoption checklist](../playbooks/package-adoption/PackageAdoptionChecklist.md) diff --git a/guidance/examples/README.md b/guidance/examples/README.md new file mode 100644 index 000000000..610c2c8f7 --- /dev/null +++ b/guidance/examples/README.md @@ -0,0 +1,8 @@ +# Examples + +This area is reserved for worked examples as the repository grows. + +## Current entry points + +- [Test repositories](../../communities/quality-assurance/test-repositories.md) +- [Technical debt monitoring](../../policies/engineering/technical-debt/TechnicalDebtMonitoring.md) diff --git a/guidance/how-to/README.md b/guidance/how-to/README.md new file mode 100644 index 000000000..3ddd8e9bb --- /dev/null +++ b/guidance/how-to/README.md @@ -0,0 +1,9 @@ +# How-to guidance + +## Key areas + +- [Cloud development](./cloud-development/README.md) +- [GitHub](./github/README.md) +- [Induction](./induction/README.md) +- [Infrastructure as code](./infrastructure-as-code/README.md) +- [Logging](./logging/README.md) diff --git a/software-engineering-policies/CloudDevelopment/CloudFirst.md b/guidance/how-to/cloud-development/CloudFirst.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/CloudFirst.md rename to guidance/how-to/cloud-development/CloudFirst.md diff --git a/software-engineering-policies/CloudDevelopment/Containers.md b/guidance/how-to/cloud-development/Containers.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/Containers.md rename to guidance/how-to/cloud-development/Containers.md diff --git a/software-engineering-policies/CloudDevelopment/DataUse.md b/guidance/how-to/cloud-development/DataUse.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/DataUse.md rename to guidance/how-to/cloud-development/DataUse.md diff --git a/software-engineering-policies/CloudDevelopment/Deployment.md b/guidance/how-to/cloud-development/Deployment.md similarity index 97% rename from software-engineering-policies/CloudDevelopment/Deployment.md rename to guidance/how-to/cloud-development/Deployment.md index 17233b75e..6052e5ae8 100644 --- a/software-engineering-policies/CloudDevelopment/Deployment.md +++ b/guidance/how-to/cloud-development/Deployment.md @@ -14,7 +14,7 @@ As mentioned above, Static Application Security Testing (SAST) takes place when ## Container Scanning -Once a container has been built within your pipeline, but prior to being pushed into a container registry it is advised to perform a Container Scan to check for vulnerabilities. Further information around our container policies can be found within the [Containers area.](/software-engineering-policies/Containers/) +Once a container has been built within your pipeline, but prior to being pushed into a container registry it is advised to perform a Container Scan to check for vulnerabilities. Further information around our container policies can be found within the [Containers area](/policies/platform/containers/ContainerPolicy.md). ## Dependency Checking for Cloud Applications diff --git a/software-engineering-policies/CloudDevelopment/DisasterRecoveryBusinessContinuity.md b/guidance/how-to/cloud-development/DisasterRecoveryBusinessContinuity.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/DisasterRecoveryBusinessContinuity.md rename to guidance/how-to/cloud-development/DisasterRecoveryBusinessContinuity.md diff --git a/software-engineering-policies/CloudDevelopment/General.md b/guidance/how-to/cloud-development/General.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/General.md rename to guidance/how-to/cloud-development/General.md diff --git a/software-engineering-policies/CloudDevelopment/LoggingAndMonitoring.md b/guidance/how-to/cloud-development/LoggingAndMonitoring.md similarity index 77% rename from software-engineering-policies/CloudDevelopment/LoggingAndMonitoring.md rename to guidance/how-to/cloud-development/LoggingAndMonitoring.md index 8edb5ca21..6480a5495 100644 --- a/software-engineering-policies/CloudDevelopment/LoggingAndMonitoring.md +++ b/guidance/how-to/cloud-development/LoggingAndMonitoring.md @@ -14,7 +14,7 @@ Logging Recommendations: * Agree on appropriate formats and logging levels to ensure logs are available and useful in maintaining your services * Consider options to control log access and ensure logs are free from unnecessary sensitive data -Please view the [Software Engineering Team Logging Policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/Logging/LoggingPolicy.md) and the [UKHO's security-focused Logging and Monitoring Policy](https://ukho.sharepoint.com/sites/docstore-prd/_layouts/15/Doc.aspx?sourcedoc=%7B925F1410-7556-4B0E-8437-25497AED4562%7D&file=POL210.docx&action=default&mobileredirect=true&DefaultItemOpen=1) on SharePoint for further guidance on how and what to log. +Please view the [Software Engineering Team Logging Policy](../logging/LoggingPolicy.md) and the [UKHO's security-focused Logging and Monitoring Policy](https://ukho.sharepoint.com/sites/docstore-prd/_layouts/15/Doc.aspx?sourcedoc=%7B925F1410-7556-4B0E-8437-25497AED4562%7D&file=POL210.docx&action=default&mobileredirect=true&DefaultItemOpen=1) on SharePoint for further guidance on how and what to log. Monitoring Recommendations diff --git a/software-engineering-policies/CloudDevelopment/PilotsLicense.md b/guidance/how-to/cloud-development/PilotsLicense.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/PilotsLicense.md rename to guidance/how-to/cloud-development/PilotsLicense.md diff --git a/software-engineering-policies/CloudDevelopment/README.md b/guidance/how-to/cloud-development/README.md similarity index 81% rename from software-engineering-policies/CloudDevelopment/README.md rename to guidance/how-to/cloud-development/README.md index c36ad308e..55390ee10 100644 --- a/software-engineering-policies/CloudDevelopment/README.md +++ b/guidance/how-to/cloud-development/README.md @@ -1,5 +1,7 @@ # Cloud Development Policy +This area currently acts as the main cloud development guidance hub while the repository is being restructured. + ## Purpose of this policy The purpose of this policy is to establish guidelines and procedures for the appropriate and secure utilization of cloud resources in software engineering within the UK Hydrographic Office. @@ -52,6 +54,12 @@ This policy applies to all software engineering teams and individuals within the [Nautilus Account Types & Purposes](https://ukho.sharepoint.com/sites/SoftwareDevandTest/SitePages/Account-types.aspx) -[Code Review Policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/CodeReview/CodeReviewPolicy.md) +[Code Review Policy](../../../policies/engineering/code-review/CodeReviewPolicy.md) + +[Container Policy](../../../policies/platform/containers/ContainerPolicy.md) + +## Related areas -[Container Policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/Containers/ContainerPolicy.md) +- [Data engineering](../../../communities/data-engineering/README.md) +- [Platform policies](../../../policies/platform/README.md) +- [Observability standards](../../../standards/observability/README.md) diff --git a/software-engineering-policies/CloudDevelopment/Tagging.md b/guidance/how-to/cloud-development/Tagging.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/Tagging.md rename to guidance/how-to/cloud-development/Tagging.md diff --git a/software-engineering-policies/CloudDevelopment/Users.md b/guidance/how-to/cloud-development/Users.md similarity index 100% rename from software-engineering-policies/CloudDevelopment/Users.md rename to guidance/how-to/cloud-development/Users.md diff --git a/software-engineering-policies/CloudDevelopment/images/Difference-between-anonymization-and-pseudonymization.png b/guidance/how-to/cloud-development/images/Difference-between-anonymization-and-pseudonymization.png similarity index 100% rename from software-engineering-policies/CloudDevelopment/images/Difference-between-anonymization-and-pseudonymization.png rename to guidance/how-to/cloud-development/images/Difference-between-anonymization-and-pseudonymization.png diff --git a/guidance/how-to/github/README.md b/guidance/how-to/github/README.md new file mode 100644 index 000000000..b762600b7 --- /dev/null +++ b/guidance/how-to/github/README.md @@ -0,0 +1,54 @@ +# GitHub guidance + +Practical guidance for working with GitHub repositories and contribution flows. + +## Background + +This guidance explains what should exist in open repositories so people can browse them comfortably, find information quickly, and contribute productively. + +## Overview + +All open repositories should contain the following: + +* **A `CONTRIBUTING.md` within the root folder.** The file signals that the repository accepts contributions and explains the process contributors should follow. Use [guidance on how to write a `CONTRIBUTING.md`](./creating-a-contributing-file.md). +* **A `LICENSE` within the root folder.** This will be MIT in most cases. Having a license is critical as it states what others are allowed to do with the code. +* **A `README.md` within the root folder.** This should contain basic useful information to help users understand the project and get started. Use [guidance on how to write a `README.md`](./creating-a-readme-file.md). +* **A continuous integration build process.** Each time a pull request is submitted a build should run the tests and provide feedback to contributors. + +Other useful repository assets may include: + +* Code of Conduct + * [Code of Conduct from contributor covenant](https://www.contributor-covenant.org/). +* Changelog + * [Keep a changelog](http://keepachangelog.com/en/0.3.0/). +* TDL (Technical decision log) + * [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + * [Architecture Decision Records In action presentation](https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf). +* Scripts + * `script/bootstrap` - configure the machine ready to develop for this repository + * `script/dev` - start any background processes or servers needed during development + * `script/test` - run all tests for the repository + +## Code contribution process + +All open repositories must use git and contributions should follow the standard fork and pull request approach, or an approved equivalent. Use [guidance on how to make a pull request](./pull-request-details.md). + +## Related areas + +- [Platform policies](../../../policies/platform/README.md) +- [Source control standards](../../../standards/source-control/README.md) +- [Root contribution guidance](../../../CONTRIBUTING.md) + +## Terminology + +`Contributing` - more than adding code; it also includes creating issues, bug reports, asking questions, and improving documentation. + +`Contributor` - anyone who has added to the project, including filing issues. + +`Repo` - a git repository and the associated GitHub or GitLab project. + +`Pull Request` - how a contributor asks the owner of a repository to accept their contribution. + +## Inspiration + +[Alpha Gov - Open Standards](https://github.com/alphagov/open-standards) diff --git a/using-github/creating-a-contributing-file.md b/guidance/how-to/github/creating-a-contributing-file.md similarity index 100% rename from using-github/creating-a-contributing-file.md rename to guidance/how-to/github/creating-a-contributing-file.md diff --git a/using-github/creating-a-readme-file.md b/guidance/how-to/github/creating-a-readme-file.md similarity index 100% rename from using-github/creating-a-readme-file.md rename to guidance/how-to/github/creating-a-readme-file.md diff --git a/using-github/migrating-to-github.md b/guidance/how-to/github/migrating-to-github.md similarity index 64% rename from using-github/migrating-to-github.md rename to guidance/how-to/github/migrating-to-github.md index 379698adc..5436aae4c 100644 --- a/using-github/migrating-to-github.md +++ b/guidance/how-to/github/migrating-to-github.md @@ -2,7 +2,7 @@ ## Remove sensitive data -As part of [the Open Source Governance Checklist](../software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md), it is a requirement that sensitive data has been removed from the repository history. This can be acheived with Git's `filter-branch` command to walk over the history of a branch and apply changes throughout. +As part of [the Open Source Governance Checklist](../../../policies/platform/open-source-contribution/OpenSourceGovernanceChecklist.md), it is a requirement that sensitive data has been removed from the repository history. This can be acheived with Git's `filter-branch` command to walk over the history of a branch and apply changes throughout. ## Remove lines from commit messages diff --git a/using-github/pull-request-details.md b/guidance/how-to/github/pull-request-details.md similarity index 100% rename from using-github/pull-request-details.md rename to guidance/how-to/github/pull-request-details.md diff --git a/software-engineering-policies/Induction/LeadDeveloperInduction.md b/guidance/how-to/induction/LeadDeveloperInduction.md similarity index 100% rename from software-engineering-policies/Induction/LeadDeveloperInduction.md rename to guidance/how-to/induction/LeadDeveloperInduction.md diff --git a/guidance/how-to/induction/README.md b/guidance/how-to/induction/README.md new file mode 100644 index 000000000..28be3d65a --- /dev/null +++ b/guidance/how-to/induction/README.md @@ -0,0 +1,6 @@ +# Induction guidance + +## Key documents + +- [Lead developer induction](./LeadDeveloperInduction.md) +- [Setting up your MSDN](./SettingUpYourMSDN.md) diff --git a/software-engineering-policies/Induction/SettingUpYourMSDN.md b/guidance/how-to/induction/SettingUpYourMSDN.md similarity index 100% rename from software-engineering-policies/Induction/SettingUpYourMSDN.md rename to guidance/how-to/induction/SettingUpYourMSDN.md diff --git a/guidance/how-to/infrastructure-as-code/README.md b/guidance/how-to/infrastructure-as-code/README.md new file mode 100644 index 000000000..999b620cc --- /dev/null +++ b/guidance/how-to/infrastructure-as-code/README.md @@ -0,0 +1,9 @@ +# Infrastructure as code guidance + +## Key documents + +- [Terraform guidance](./terraform.md) + +## Related areas + +- [Platform policies](../../../policies/platform/README.md) diff --git a/software-engineering-policies/InfrastructureAsCode/terraform.md b/guidance/how-to/infrastructure-as-code/terraform.md similarity index 100% rename from software-engineering-policies/InfrastructureAsCode/terraform.md rename to guidance/how-to/infrastructure-as-code/terraform.md diff --git a/software-engineering-policies/Logging/GuidanceForLoggingToElasticCloud.md b/guidance/how-to/logging/GuidanceForLoggingToElasticCloud.md similarity index 100% rename from software-engineering-policies/Logging/GuidanceForLoggingToElasticCloud.md rename to guidance/how-to/logging/GuidanceForLoggingToElasticCloud.md diff --git a/software-engineering-policies/Logging/LoggingPolicy.md b/guidance/how-to/logging/LoggingPolicy.md similarity index 100% rename from software-engineering-policies/Logging/LoggingPolicy.md rename to guidance/how-to/logging/LoggingPolicy.md diff --git a/guidance/how-to/logging/README.md b/guidance/how-to/logging/README.md new file mode 100644 index 000000000..4212172ec --- /dev/null +++ b/guidance/how-to/logging/README.md @@ -0,0 +1,10 @@ +# Logging guidance + +## Key documents + +- [Guidance for logging to Elastic Cloud](./GuidanceForLoggingToElasticCloud.md) +- [Logging policy](./LoggingPolicy.md) + +## Related areas + +- [Observability standards](../../../standards/observability/README.md) diff --git a/guidance/playbooks/README.md b/guidance/playbooks/README.md new file mode 100644 index 000000000..efc9353cc --- /dev/null +++ b/guidance/playbooks/README.md @@ -0,0 +1,5 @@ +# Playbooks + +## Key areas + +- [Package adoption](./package-adoption/README.md) diff --git a/software-engineering-policies/PackageAdoption/PackageAdoptionChecklist.md b/guidance/playbooks/package-adoption/PackageAdoptionChecklist.md similarity index 100% rename from software-engineering-policies/PackageAdoption/PackageAdoptionChecklist.md rename to guidance/playbooks/package-adoption/PackageAdoptionChecklist.md diff --git a/software-engineering-policies/PackageAdoption/PackageAdoptionGuidance.md b/guidance/playbooks/package-adoption/PackageAdoptionGuidance.md similarity index 100% rename from software-engineering-policies/PackageAdoption/PackageAdoptionGuidance.md rename to guidance/playbooks/package-adoption/PackageAdoptionGuidance.md diff --git a/software-engineering-policies/PackageAdoption/PackageAdoptionPolicy.md b/guidance/playbooks/package-adoption/PackageAdoptionPolicy.md similarity index 62% rename from software-engineering-policies/PackageAdoption/PackageAdoptionPolicy.md rename to guidance/playbooks/package-adoption/PackageAdoptionPolicy.md index 55e6b63b3..ec412b5b8 100644 --- a/software-engineering-policies/PackageAdoption/PackageAdoptionPolicy.md +++ b/guidance/playbooks/package-adoption/PackageAdoptionPolicy.md @@ -2,7 +2,7 @@ ## Overview -UKHO has a [code reuse policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/CodeReuse/CodeReusePolicy.md) such that, where possible, we should be reusing assets. One way of achieving this is creating packages which can then be integrated by multiple teams. These packages have traditionally been the responsibility of the team that created them; however over time teams have changed according to business requirements and this has left a number of packages "orphaned" e.g. they only receive any attention if an integrating team find a vulnerability or can no longer utilise the package because it is using an out-of-support version of it's language, etc. +UKHO has a [code reuse policy](../../../policies/engineering/code-reuse/CodeReusePolicy.md) such that, where possible, we should be reusing assets. One way of achieving this is creating packages which can then be integrated by multiple teams. These packages have traditionally been the responsibility of the team that created them; however over time teams have changed according to business requirements and this has left a number of packages "orphaned" e.g. they only receive any attention if an integrating team find a vulnerability or can no longer utilise the package because it is using an out-of-support version of it's language, etc. ## Aim diff --git a/guidance/playbooks/package-adoption/README.md b/guidance/playbooks/package-adoption/README.md new file mode 100644 index 000000000..c2b00edcb --- /dev/null +++ b/guidance/playbooks/package-adoption/README.md @@ -0,0 +1,11 @@ +# Package adoption playbook + +## Key documents + +- [Package adoption policy](./PackageAdoptionPolicy.md) +- [Package adoption guidance](./PackageAdoptionGuidance.md) +- [Package adoption checklist](./PackageAdoptionChecklist.md) + +## Related areas + +- [Engineering policies](../../../policies/engineering/README.md) diff --git a/policies/README.md b/policies/README.md new file mode 100644 index 000000000..096938de3 --- /dev/null +++ b/policies/README.md @@ -0,0 +1,11 @@ +# Policies + +Use the policies area for mandatory requirements and approved policy statements. + +## Areas + +- [Engineering](./engineering/README.md) +- [Security](./security/README.md) +- [Testing](./testing/README.md) +- [Data](./data/README.md) +- [Platform](./platform/README.md) diff --git a/policies/data/README.md b/policies/data/README.md new file mode 100644 index 000000000..216cf8685 --- /dev/null +++ b/policies/data/README.md @@ -0,0 +1,9 @@ +# Data policies + +This area is reserved for mandatory data-specific policies as the repository grows. + +## Current entry points + +- [Data engineering community](../../communities/data-engineering/README.md) +- [Data use in the cloud](../../guidance/how-to/cloud-development/DataUse.md) +- [Security policies](../security/README.md) diff --git a/policies/engineering/README.md b/policies/engineering/README.md new file mode 100644 index 000000000..6f78d7dbe --- /dev/null +++ b/policies/engineering/README.md @@ -0,0 +1,20 @@ +# Engineering policies + +Mandatory policy statements for software engineering practices. + +## Key documents + +- [Code copyright](./code-copyright/CodeCopyrightPolicy.md) +- [Code generation tools](./code-generation-tools/CodeGenerationToolsPolicy.md) +- [Code reuse](./code-reuse/CodeReusePolicy.md) +- [Code review](./code-review/CodeReviewPolicy.md) +- [Front-end](./front-end/FrontEndPolicy.md) +- [Inclusive language](./inclusive-language/InclusiveLanguagePolicy.md) +- [Non-functional requirements](./non-functional-requirements/NFRPolicy.md) +- [Pair programming](./pair-programming/PairProgrammingPolicy.md) +- [Technical debt](./technical-debt/TechnicalDebtPolicy.md) + +## Related areas + +- [Software engineering community](../../communities/software-engineering/README.md) +- [Coding standards](../../standards/coding/README.md) diff --git a/software-engineering-policies/CodeCopyright/CodeCopyrightPolicy.md b/policies/engineering/code-copyright/CodeCopyrightPolicy.md similarity index 79% rename from software-engineering-policies/CodeCopyright/CodeCopyrightPolicy.md rename to policies/engineering/code-copyright/CodeCopyrightPolicy.md index c0574cae9..389843185 100644 --- a/software-engineering-policies/CodeCopyright/CodeCopyrightPolicy.md +++ b/policies/engineering/code-copyright/CodeCopyrightPolicy.md @@ -6,6 +6,6 @@ All the code we create is [Crown copyright](https://www.nationalarchives.gov.uk/ We are encouraged to open source and license our code under the [Open Government License](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/open-government-licence/open-software-licences/), but are given freedom to use another open source license if we think it would promote adoption. -If we want to open source code we should use the [MIT license as per the policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/OpenSourceContribution/OpenSourceContributionPolicy.md) (appendix A). This should assert Crown copyright, as per the example “Copyright (C) 2011 Crown copyright (United Kingdom Hydrographic Office)”). +If we want to open source code we should use the [MIT license as per the policy](../../platform/open-source-contribution/OpenSourceContributionPolicy.md) (appendix A). This should assert Crown copyright, as per the example “Copyright (C) 2011 Crown copyright (United Kingdom Hydrographic Office)”). Where we are not open sourcing, if there is no license explicitly included in a repo then no license is granted. We can just miss out the license file. We should still assert Crown copyright. Since there will be no license file, it should go somewhere prominent like a readme. We don’t need to repeat it in every source file. diff --git a/software-engineering-policies/CodeGenerationTools/CodeGenerationToolsPolicy.md b/policies/engineering/code-generation-tools/CodeGenerationToolsPolicy.md similarity index 100% rename from software-engineering-policies/CodeGenerationTools/CodeGenerationToolsPolicy.md rename to policies/engineering/code-generation-tools/CodeGenerationToolsPolicy.md diff --git a/software-engineering-policies/CodeReuse/CodeReusePolicy.md b/policies/engineering/code-reuse/CodeReusePolicy.md similarity index 100% rename from software-engineering-policies/CodeReuse/CodeReusePolicy.md rename to policies/engineering/code-reuse/CodeReusePolicy.md diff --git a/software-engineering-policies/CodeReview/CodeReviewPolicy.md b/policies/engineering/code-review/CodeReviewPolicy.md similarity index 100% rename from software-engineering-policies/CodeReview/CodeReviewPolicy.md rename to policies/engineering/code-review/CodeReviewPolicy.md diff --git a/software-engineering-policies/FrontEnd/FrontEndPolicy.md b/policies/engineering/front-end/FrontEndPolicy.md similarity index 100% rename from software-engineering-policies/FrontEnd/FrontEndPolicy.md rename to policies/engineering/front-end/FrontEndPolicy.md diff --git a/software-engineering-policies/InclusiveLanguage/InclusiveLanguagePolicy.md b/policies/engineering/inclusive-language/InclusiveLanguagePolicy.md similarity index 100% rename from software-engineering-policies/InclusiveLanguage/InclusiveLanguagePolicy.md rename to policies/engineering/inclusive-language/InclusiveLanguagePolicy.md diff --git a/software-engineering-policies/NFRs/NFRPolicy.md b/policies/engineering/non-functional-requirements/NFRPolicy.md similarity index 100% rename from software-engineering-policies/NFRs/NFRPolicy.md rename to policies/engineering/non-functional-requirements/NFRPolicy.md diff --git a/software-engineering-policies/PairProgramming/PairProgrammingPolicy.md b/policies/engineering/pair-programming/PairProgrammingPolicy.md similarity index 100% rename from software-engineering-policies/PairProgramming/PairProgrammingPolicy.md rename to policies/engineering/pair-programming/PairProgrammingPolicy.md diff --git a/software-engineering-policies/TechnicalDebt/Example_TD_V4.png b/policies/engineering/technical-debt/Example_TD_V4.png similarity index 100% rename from software-engineering-policies/TechnicalDebt/Example_TD_V4.png rename to policies/engineering/technical-debt/Example_TD_V4.png diff --git a/software-engineering-policies/TechnicalDebt/Porfolio_TD_V1.png b/policies/engineering/technical-debt/Porfolio_TD_V1.png similarity index 100% rename from software-engineering-policies/TechnicalDebt/Porfolio_TD_V1.png rename to policies/engineering/technical-debt/Porfolio_TD_V1.png diff --git a/software-engineering-policies/TechnicalDebt/TechnicalDebtMonitoring.md b/policies/engineering/technical-debt/TechnicalDebtMonitoring.md similarity index 100% rename from software-engineering-policies/TechnicalDebt/TechnicalDebtMonitoring.md rename to policies/engineering/technical-debt/TechnicalDebtMonitoring.md diff --git a/software-engineering-policies/TechnicalDebt/TechnicalDebtPolicy.md b/policies/engineering/technical-debt/TechnicalDebtPolicy.md similarity index 100% rename from software-engineering-policies/TechnicalDebt/TechnicalDebtPolicy.md rename to policies/engineering/technical-debt/TechnicalDebtPolicy.md diff --git a/software-engineering-policies/TechnicalDebt/dashboard_TD_V1.png b/policies/engineering/technical-debt/dashboard_TD_V1.png similarity index 100% rename from software-engineering-policies/TechnicalDebt/dashboard_TD_V1.png rename to policies/engineering/technical-debt/dashboard_TD_V1.png diff --git a/policies/platform/README.md b/policies/platform/README.md new file mode 100644 index 000000000..15d9fc0c5 --- /dev/null +++ b/policies/platform/README.md @@ -0,0 +1,16 @@ +# Platform policies + +Mandatory policy statements for platform, delivery, and open-source governance. + +## Key documents + +- [Containers](./containers/ContainerPolicy.md) +- [Open source contribution](./open-source-contribution/OpenSourceContributionPolicy.md) +- [Open source use](./open-source-use/OpenSourceUsePolicy.md) +- [Pipelines](./pipelines/baseline-policy.md) +- [Third-party licensing](./third-party-licensing/ThirdPartyLicensingPolicy.md) + +## Related areas + +- [GitHub guidance](../../guidance/how-to/github/README.md) +- [Source control standards](../../standards/source-control/README.md) diff --git a/software-engineering-policies/Containers/ContainerBestPractices.md b/policies/platform/containers/ContainerBestPractices.md similarity index 100% rename from software-engineering-policies/Containers/ContainerBestPractices.md rename to policies/platform/containers/ContainerBestPractices.md diff --git a/software-engineering-policies/Containers/ContainerPolicy.md b/policies/platform/containers/ContainerPolicy.md similarity index 100% rename from software-engineering-policies/Containers/ContainerPolicy.md rename to policies/platform/containers/ContainerPolicy.md diff --git a/software-engineering-policies/OpenSourceContribution/OpenSourceContributionPolicy.md b/policies/platform/open-source-contribution/OpenSourceContributionPolicy.md similarity index 100% rename from software-engineering-policies/OpenSourceContribution/OpenSourceContributionPolicy.md rename to policies/platform/open-source-contribution/OpenSourceContributionPolicy.md diff --git a/software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md b/policies/platform/open-source-contribution/OpenSourceGovernanceChecklist.md similarity index 100% rename from software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md rename to policies/platform/open-source-contribution/OpenSourceGovernanceChecklist.md diff --git a/software-engineering-policies/OpenSourceUse/OpenSourceUsePolicy.md b/policies/platform/open-source-use/OpenSourceUsePolicy.md similarity index 100% rename from software-engineering-policies/OpenSourceUse/OpenSourceUsePolicy.md rename to policies/platform/open-source-use/OpenSourceUsePolicy.md diff --git a/software-engineering-policies/Pipelines/Baseline_Policy.md b/policies/platform/pipelines/baseline-policy.md similarity index 100% rename from software-engineering-policies/Pipelines/Baseline_Policy.md rename to policies/platform/pipelines/baseline-policy.md diff --git a/software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingGuidance.md b/policies/platform/third-party-licensing/ThirdPartyLicensingGuidance.md similarity index 100% rename from software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingGuidance.md rename to policies/platform/third-party-licensing/ThirdPartyLicensingGuidance.md diff --git a/software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingPolicy.md b/policies/platform/third-party-licensing/ThirdPartyLicensingPolicy.md similarity index 100% rename from software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingPolicy.md rename to policies/platform/third-party-licensing/ThirdPartyLicensingPolicy.md diff --git a/policies/security/README.md b/policies/security/README.md new file mode 100644 index 000000000..cfc16fd1f --- /dev/null +++ b/policies/security/README.md @@ -0,0 +1,12 @@ +# Security policies + +Mandatory policy statements for secure software delivery. + +## Key documents + +- [Secure development](./secure-development/SecureDevelopmentPolicy.md) + +## Related areas + +- [Security community](../../communities/security/README.md) +- [Observability standards](../../standards/observability/README.md) diff --git a/software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md b/policies/security/secure-development/SecureDevelopmentPolicy.md similarity index 94% rename from software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md rename to policies/security/secure-development/SecureDevelopmentPolicy.md index 5fe281240..5bb45103e 100644 --- a/software-engineering-policies/SecureDevelopment/SecureDevelopmentPolicy.md +++ b/policies/security/secure-development/SecureDevelopmentPolicy.md @@ -24,7 +24,7 @@ This can be due to several reasons, including lack of training, accidental, insu The purpose of this document is to ensure that: -- It is clear what controls are expected - see [Managing Security Concerns Policy](../../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) +- It is clear what controls are expected - see [Managing Security Concerns Policy](../../../communities/security/managing-security-concerns.md) - It is clear what roles are required. @@ -76,7 +76,7 @@ The risk owner is the person who is responsible for the product. This may be the - Security considerations must be included within the Definition of Done. - Security-related stories (vulnerabilities, upgrades) must be raised in TFS with the ‘Security’ and ‘Security Concern’ tag. -- See also the [Managing Security Concerns Policy](../../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) +- See also the [Managing Security Concerns Policy](../../../communities/security/managing-security-concerns.md) ### Skills Matrix @@ -98,7 +98,7 @@ The risk owner is the person who is responsible for the product. This may be the >_Source control is a key requirement for projects as it provides role-based access control to code, change management and a changelog._ - All project code intended for delivery should be stored as per the UKHO source control policy. -- Source control repositories should conform to the policies as [found here](../SourceControl/SourceControlPolicy.md) +- Source control repositories should conform to the policies as [found here](../../../standards/source-control/source-control/SourceControlPolicy.md) ### 3rd Party Dependency/Package Management @@ -126,7 +126,7 @@ The risk owner is the person who is responsible for the product. This may be the >_Each project will have recurring pieces of functionality. These generic PBIs should be captured, threat-modelled, and have code mitigations agreed. OWASP vulnerabilities should be discussed such as XSS, SQL Injections, broken authentication/authorisation, direct object referencing etc. It is easier to review and catch vulnerabilities during code reviews if everyone tackles vulnerabilities with the same techniques._ - Each team must document a set of generic scenarios for their project. -- The team must follow a [threat modelling process](../../security/ThreatModelling/ThreatModelling.md). +- The team must follow a [threat modelling process](../../../communities/security/threat-modelling.md). - Each team must agree on standard code approaches to mitigate common vulnerabilities. - A code review checklist must be generated from the results of threat modelling. - Testing criteria must be agreed and recorded within the solution. diff --git a/policies/testing/README.md b/policies/testing/README.md new file mode 100644 index 000000000..f46423c98 --- /dev/null +++ b/policies/testing/README.md @@ -0,0 +1,13 @@ +# Testing policies + +Mandatory policy statements for testing and delivery assurance. + +## Key documents + +- [Defect management](./defect-management/DefectManagementPolicy.md) +- [Unit testing](./unit-testing/UnitTestingPolicy.md) + +## Related areas + +- [Quality assurance community](../../communities/quality-assurance/README.md) +- [Testing standards](../../standards/testing/README.md) diff --git a/software-engineering-policies/DefectManagement/DefectManagementPolicy.md b/policies/testing/defect-management/DefectManagementPolicy.md similarity index 100% rename from software-engineering-policies/DefectManagement/DefectManagementPolicy.md rename to policies/testing/defect-management/DefectManagementPolicy.md diff --git a/software-engineering-policies/UnitTesting/UnitTestingPolicy.md b/policies/testing/unit-testing/UnitTestingPolicy.md similarity index 100% rename from software-engineering-policies/UnitTesting/UnitTestingPolicy.md rename to policies/testing/unit-testing/UnitTestingPolicy.md diff --git a/reference/README.md b/reference/README.md new file mode 100644 index 000000000..55f75be3e --- /dev/null +++ b/reference/README.md @@ -0,0 +1,9 @@ +# Reference + +Use the reference area for supporting roles, technology radar material, templates, and other supporting information. + +## Areas + +- [Roles](./roles/README.md) +- [Technology radar](./technology-radar/README.md) +- [Templates](./templates/README.md) diff --git a/reference/roles/README.md b/reference/roles/README.md new file mode 100644 index 000000000..38ee52317 --- /dev/null +++ b/reference/roles/README.md @@ -0,0 +1,10 @@ +# Roles reference + +## Key documents + +- [Engineering team](./engineering-team.md) +- [Principal developer](./principal-developer.md) + +## Related areas + +- [Software engineering community](../../communities/software-engineering/README.md) diff --git a/software-engineering-policies/engineering-team.md b/reference/roles/engineering-team.md similarity index 100% rename from software-engineering-policies/engineering-team.md rename to reference/roles/engineering-team.md diff --git a/communities/software-engineering/roles/principal-developer.md b/reference/roles/principal-developer.md similarity index 100% rename from communities/software-engineering/roles/principal-developer.md rename to reference/roles/principal-developer.md diff --git a/reference/technology-radar/README.md b/reference/technology-radar/README.md new file mode 100644 index 000000000..28564e32b --- /dev/null +++ b/reference/technology-radar/README.md @@ -0,0 +1,8 @@ +# Technology radar + +## Key documents + +- [Public radar data](./public-radar.csv) +- [Technology governance](./technology-governance/TechnologyGovernance.md) + +The public radar data can be used with the Thoughtworks radar viewer when needed. diff --git a/software-engineering-policies/PublicRadar.csv b/reference/technology-radar/public-radar.csv similarity index 100% rename from software-engineering-policies/PublicRadar.csv rename to reference/technology-radar/public-radar.csv diff --git a/software-engineering-policies/TechnologyGovernance/TechnologyGovernance.md b/reference/technology-radar/technology-governance/TechnologyGovernance.md similarity index 100% rename from software-engineering-policies/TechnologyGovernance/TechnologyGovernance.md rename to reference/technology-radar/technology-governance/TechnologyGovernance.md diff --git a/reference/templates/README.md b/reference/templates/README.md new file mode 100644 index 000000000..48ec4418e --- /dev/null +++ b/reference/templates/README.md @@ -0,0 +1,10 @@ +# Templates and supporting assets + +## Key assets + +- [Baseline pipeline diagram](./resources/baseline-diagram.png) +- [Pipeline control options](./resources/control-options.png) + +## Related areas + +- [Platform policies](../../policies/platform/README.md) diff --git a/software-engineering-policies/Resources/baseline-diagram.png b/reference/templates/resources/baseline-diagram.png similarity index 100% rename from software-engineering-policies/Resources/baseline-diagram.png rename to reference/templates/resources/baseline-diagram.png diff --git a/software-engineering-policies/Resources/control-options.png b/reference/templates/resources/control-options.png similarity index 100% rename from software-engineering-policies/Resources/control-options.png rename to reference/templates/resources/control-options.png diff --git a/software-engineering-policies/CONTRIBUTING.md b/software-engineering-policies/CONTRIBUTING.md deleted file mode 100644 index 992f5b15e..000000000 --- a/software-engineering-policies/CONTRIBUTING.md +++ /dev/null @@ -1,26 +0,0 @@ -# Contributing to Software Engineering Policies - -Thank you for considering to contributing to these policies - -## Contribution Processes - -### Questions, Queries and Concerns - -Please open an issue in all situations and if necessary please `@` the policy owner and editor. - -### Minor Changes (typos etc.) - -Please make the change on a separate branch and submit a merge request. - -### Major Changes (Updating/Creating policies) - -- Open an issue containing detailed information on the change you would like to make -- If you want to change and existing policy, please `@` the policy owner and editor -- Add the `proposal` label to the issue. -- With other participants and stakeholders come to a consensus whether to accept the proposal -- If accepted **remove the `proposal` label and replace with `accepted`.** This should only be done with agreement from the owner (if relevant) -- Make the accepted changes on a separate branch, push to GitLab and open a merge request for review -- Once the changes have been reviewed, make all requested changes. This can take several rounds of `changes` -> `review` -- Once the review is complete and all requested changes have been made, merge in the accepted branch - -> If your proposal is rejected, please close the issue and feel free to resubmit in a new issue making the necessary changes. diff --git a/software-engineering-policies/README.md b/software-engineering-policies/README.md deleted file mode 100644 index defa5ec9f..000000000 --- a/software-engineering-policies/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Software Engineering Policies - -The policies (and associated guidance) that should be followed during software development at the UKHO. - -| Area | Policy | Guidance | -| :--- | :--- | :--- | -| Code Copyright | [Policy](CodeCopyright/CodeCopyrightPolicy.md) | | -| Code Reuse | [Policy](CodeReuse/CodeReusePolicy.md) | | -| Code Review | [Policy](CodeReview/CodeReviewPolicy.md) | | -| Containers | [Policy](Containers/ContainerPolicy.md) | | -| Defect Management | [Policy](DefectManagement/DefectManagementPolicy.md) | | -| Inclusive Language | [Policy](InclusiveLanguage/InclusiveLanguagePolicy.md) | | -| Machine learning and AI developments | [Policy on SharePoint](https://ukho.sharepoint.com/sites/DataScienceandEngineering/SitePages/Machine-learning-and-AI-developments.aspx) | [AI programming assistants guidance](https://ukho.sharepoint.com/sites/DataScienceandEngineering/SitePages/AI-programming-assistants-guidance.aspx)
[Release models for machine learning models](https://ukho.sharepoint.com/sites/DataScienceandEngineering/SitePages/Release-models-for-machine-learning-models.aspx) | -| Non Functional Requirements | [Policy](NFRs/NFRPolicy.md) | | -| Open Source Contribution | [Policy](OpenSourceContribution/OpenSourceContributionPolicy.md) | | -| Open Source Use | [Policy](OpenSourceUse/OpenSourceUsePolicy.md) | | -| Pair Programming | [Policy](PairProgramming/PairProgrammingPolicy.md) | | -| Secure Development | [Policy](SecureDevelopment/SecureDevelopmentPolicy.md) | | -|   Managing Security Concerns | [Policy](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) | and [CVSS Scoring Guidance](../security/ManagingSecurityConcerns/CvssScoringMetrics.md)| -| Source Control | [Policy](SourceControl/SourceControlPolicy.md) | | -| System Documentation | [Policy](SystemDocumentation/SystemDocumentationPolicy.md) | | -| Technical Debt | [Policy](TechnicalDebt/TechnicalDebtPolicy.md) | [Guidance](TechnicalDebt/TechnicalDebtGuidance.md) | -| Third-Party Licensing | [Policy](ThirdPartyLicensing/ThirdPartyLicensingPolicy.md) | [Guidance](ThirdPartyLicensing/ThirdPartyLicensingGuidance.md) | -| Unit Testing | [Policy](UnitTesting/UnitTestingPolicy.md) | [Guidance](UnitTesting/UnitTestingGuidance.md) | diff --git a/standards/README.md b/standards/README.md new file mode 100644 index 000000000..714947be6 --- /dev/null +++ b/standards/README.md @@ -0,0 +1,11 @@ +# Standards + +Use the standards area for implementation expectations and repeatable engineering standards. + +## Areas + +- [Coding](./coding/README.md) +- [Testing](./testing/README.md) +- [Source control](./source-control/README.md) +- [Observability](./observability/README.md) +- [Documentation](./documentation/README.md) diff --git a/standards/coding/README.md b/standards/coding/README.md new file mode 100644 index 000000000..784584b87 --- /dev/null +++ b/standards/coding/README.md @@ -0,0 +1,9 @@ +# Coding standards + +## Key documents + +- [Coding standards index](./coding-standards/README.md) + +## Related areas + +- [Engineering policies](../../policies/engineering/README.md) diff --git a/software-engineering-policies/CodingStandards/CssCodingStandards.md b/standards/coding/coding-standards/CssCodingStandards.md similarity index 100% rename from software-engineering-policies/CodingStandards/CssCodingStandards.md rename to standards/coding/coding-standards/CssCodingStandards.md diff --git a/software-engineering-policies/CodingStandards/DotNetCodingStandards.md b/standards/coding/coding-standards/DotNetCodingStandards.md similarity index 100% rename from software-engineering-policies/CodingStandards/DotNetCodingStandards.md rename to standards/coding/coding-standards/DotNetCodingStandards.md diff --git a/software-engineering-policies/CodingStandards/HtmlCodingStandards.md b/standards/coding/coding-standards/HtmlCodingStandards.md similarity index 100% rename from software-engineering-policies/CodingStandards/HtmlCodingStandards.md rename to standards/coding/coding-standards/HtmlCodingStandards.md diff --git a/software-engineering-policies/CodingStandards/JavascriptCodingStandards.md b/standards/coding/coding-standards/JavascriptCodingStandards.md similarity index 100% rename from software-engineering-policies/CodingStandards/JavascriptCodingStandards.md rename to standards/coding/coding-standards/JavascriptCodingStandards.md diff --git a/software-engineering-policies/CodingStandards/PythonCodingStandards.md b/standards/coding/coding-standards/PythonCodingStandards.md similarity index 100% rename from software-engineering-policies/CodingStandards/PythonCodingStandards.md rename to standards/coding/coding-standards/PythonCodingStandards.md diff --git a/software-engineering-policies/CodingStandards/README.md b/standards/coding/coding-standards/README.md similarity index 100% rename from software-engineering-policies/CodingStandards/README.md rename to standards/coding/coding-standards/README.md diff --git a/standards/documentation/README.md b/standards/documentation/README.md new file mode 100644 index 000000000..2a6451965 --- /dev/null +++ b/standards/documentation/README.md @@ -0,0 +1,12 @@ +# Documentation standards + +## Key documents + +- [Development principles](./development-principles.md) +- [Naming conventions](./naming-conventions/NamingConventions.md) +- [System documentation](./system-documentation/SystemDocumentationPolicy.md) + +## Related areas + +- [CONTRIBUTING.md](../../CONTRIBUTING.md) +- [Reference templates](../../reference/templates/README.md) diff --git a/software-engineering-policies/development-principles.md b/standards/documentation/development-principles.md similarity index 100% rename from software-engineering-policies/development-principles.md rename to standards/documentation/development-principles.md diff --git a/software-engineering-policies/NamingConventions/NamingConventions.md b/standards/documentation/naming-conventions/NamingConventions.md similarity index 100% rename from software-engineering-policies/NamingConventions/NamingConventions.md rename to standards/documentation/naming-conventions/NamingConventions.md diff --git a/software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md b/standards/documentation/system-documentation/SystemDocumentationPolicy.md similarity index 100% rename from software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md rename to standards/documentation/system-documentation/SystemDocumentationPolicy.md diff --git a/standards/observability/README.md b/standards/observability/README.md new file mode 100644 index 000000000..cba331e29 --- /dev/null +++ b/standards/observability/README.md @@ -0,0 +1,10 @@ +# Observability standards + +## Key documents + +- [Observability policy](./observability/observability-policy.md) +- [Logging guidance](../../guidance/how-to/logging/GuidanceForLoggingToElasticCloud.md) + +## Related areas + +- [Engineering policies](../../policies/engineering/README.md) diff --git a/software-engineering-policies/Observability/observability_policy.md b/standards/observability/observability/observability-policy.md similarity index 100% rename from software-engineering-policies/Observability/observability_policy.md rename to standards/observability/observability/observability-policy.md diff --git a/standards/source-control/README.md b/standards/source-control/README.md new file mode 100644 index 000000000..62effd6b7 --- /dev/null +++ b/standards/source-control/README.md @@ -0,0 +1,13 @@ +# Source control standards + +## Key documents + +- [Source control policy and guidance set](./source-control/SourceControlPolicy.md) +- [Repository setup](./source-control/RepositorySetupPolicy.md) +- [Git branch protection](./source-control/GitBranchProtectionPolicy.md) +- [Azure DevOps branch protection](./source-control/AzDoBranchProtection.md) + +## Related areas + +- [Platform policies](../../policies/platform/README.md) +- [GitHub guidance](../../guidance/how-to/github/README.md) diff --git a/software-engineering-policies/SourceControl/AzDoBranchProtection.md b/standards/source-control/source-control/AzDoBranchProtection.md similarity index 100% rename from software-engineering-policies/SourceControl/AzDoBranchProtection.md rename to standards/source-control/source-control/AzDoBranchProtection.md diff --git a/software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md b/standards/source-control/source-control/GitBranchProtectionPolicy.md similarity index 100% rename from software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md rename to standards/source-control/source-control/GitBranchProtectionPolicy.md diff --git a/software-engineering-policies/SourceControl/RepositorySetupPolicy.md b/standards/source-control/source-control/RepositorySetupPolicy.md similarity index 92% rename from software-engineering-policies/SourceControl/RepositorySetupPolicy.md rename to standards/source-control/source-control/RepositorySetupPolicy.md index 0d3c1c077..493330b36 100644 --- a/software-engineering-policies/SourceControl/RepositorySetupPolicy.md +++ b/standards/source-control/source-control/RepositorySetupPolicy.md @@ -16,7 +16,7 @@ This describes the license in which the codebase is under. ### CONTRIBUTING.md -The contributing file explains to anyone wishing to interact with the codebase how they would go about doing so. This would include raising issues, how to go about creating pull requests and any guidance to what should be included when making changes. Examples of these files can be [found here](/using-github/creating-a-contributing-file.md) +The contributing file explains to anyone wishing to interact with the codebase how they would go about doing so. This would include raising issues, how to go about creating pull requests and any guidance to what should be included when making changes. Examples of these files can be [found here](/guidance/how-to/github/creating-a-contributing-file.md) ### SECURITY.md @@ -62,7 +62,7 @@ Finally `Automatically delete head branches` is required to be enabled to suppor ## Branch Protection Rules -Branch protection should always be setup against your default branch. The policy for this can be [found here](/software-engineering-policies/SourceControl/BranchProtectionPolicy.md) +Branch protection should always be setup against your default branch. Guidance for this can be found in the [GitHub branch protection guide](/standards/source-control/source-control/GitBranchProtectionPolicy.md) and the [Azure DevOps branch protection guide](/standards/source-control/source-control/AzDoBranchProtection.md). ## Code security and analysis diff --git a/software-engineering-policies/SourceControl/SourceControlPolicy.md b/standards/source-control/source-control/SourceControlPolicy.md similarity index 93% rename from software-engineering-policies/SourceControl/SourceControlPolicy.md rename to standards/source-control/source-control/SourceControlPolicy.md index 0acd3c10f..daa38754f 100644 --- a/software-engineering-policies/SourceControl/SourceControlPolicy.md +++ b/standards/source-control/source-control/SourceControlPolicy.md @@ -11,7 +11,7 @@ ## Repository Setup -Information about setting up your repository can be [found here](/software-engineering-policies/SourceControl/RepositorySetupPolicy.md) +Information about setting up your repository can be [found here](/standards/source-control/source-control/RepositorySetupPolicy.md) ## Access control @@ -31,7 +31,7 @@ So for example if someone was working on a feature to update a button the branch `1001/feature-update-button-onclick` -Branch Protection should be setup against the main branch. Information is provided for [GitHub](/software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md) and [Azure Devops](/software-engineering-policies/SourceControl/AzDoBranchProtection.md) +Branch Protection should be setup against the main branch. Information is provided for [GitHub](/standards/source-control/source-control/GitBranchProtectionPolicy.md) and [Azure DevOps](/standards/source-control/source-control/AzDoBranchProtection.md) ## Check-in comments diff --git a/standards/testing/README.md b/standards/testing/README.md new file mode 100644 index 000000000..c2cd27c20 --- /dev/null +++ b/standards/testing/README.md @@ -0,0 +1,8 @@ +# Testing standards + +This area is reserved for testing-specific implementation standards. + +## Current entry points + +- [Test automation standards](../../communities/quality-assurance/test-code-standards.md) +- [Quality assurance community](../../communities/quality-assurance/README.md) diff --git a/using-github/readme.md b/using-github/readme.md deleted file mode 100644 index 0d8d23340..000000000 --- a/using-github/readme.md +++ /dev/null @@ -1,51 +0,0 @@ -# Our guidance for using GitHub - -## Background - -This repository is to provide guidance on what must exist in open repos as a minimum with the aim of enabling people to feel familiar when browsing, find information and to become productive if contributing back. - -## Overview - -All open repos must contain the following: - -* **A CONTRIBUTING.md within the root folder.** The file is a marker to people that this repo will accept changes from outside of the team. It must contain the processes that the owner of the repository needs people to follow when contributing to the project. [Guidance on how to write a CONTRIBUTING.md](creating-a-contributing-file.md). - -* **A LICENSE within the root folder.** This will be MIT in most cases. Having a license is critical as it states what others are allowed to do with the code. -* **A README.md within the root folder.** This must contain some basic useful information for the user allowing them to quickly understand the project and get started using it. It isn't the place for extensive documentation. [Guidance on how to write a README.md](creating-a-readme-file.md). - -* **A continuous integration build process.** Each time a pull request is submitted a build is triggered which will run all the tests to ensure the change does not break any features. This will also give the contributor feedback and confidence that their code will work! - -Above is the minimum for what an open repo must contain, other useful things a repo may contain: - -* Code of Conduct - * [Code of Conduct from contributor covenant](https://www.contributor-covenant.org/). - -* Changelog - * [Keep a changelog](http://keepachangelog.com/en/0.3.0/). - -* TDL (Technical decision log) - * [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). - * [Architecture Decision Records In action presentation](https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf). - -* Scripts - * ```script/bootstrap``` - Configure the machine ready to develop for this repo (pull down and configure dependencies etc.) - * ```script/dev``` - Start any background processes/servers needed during development - * ```script/test``` - Run all the tests for this repo. - -## Code Contribution Process - -All open repos must be using git and code contributions should be made using the standard Fork and Pull Request approach (or equivalent). [Guidance on how to make a pull request](pull-request-details.md). - -## Terminology - -```Contributing``` - This is more than just adding code, this also includes creating issues/bug reports, asking questions, improving documentation. - -```Contributor``` - This refers to anyone who has added to this project, including filing issues. - -```Repo``` - A git repository and the associated Github/lab with it. - -```Pull Request``` - How a contributor asks the owner of a repository to accept their contribution. The owner "pulls" the contribution into the main repository. - -## Inspiration - -[Alpha Gov - Open Standards](https://github.com/alphagov/open-standards) From 5bba0c832a5e37e1a122454ac2f4c1035f922f61 Mon Sep 17 00:00:00 2001 From: Martyn Fewtrell Date: Thu, 14 May 2026 11:26:08 +0100 Subject: [PATCH 3/4] Improve documentation structure and contributor guidance Add documentation.instructions.md with detailed authoring guidance, including documentation modes, mapping, and a contributor checklist. Update CONTRIBUTING.md with a mapping table for document types. Revise README.md files to clarify the purpose and navigation of each documentation area. --- .../documentation.instructions.md | 172 ++++++++++++++++++ CONTRIBUTING.md | 22 +++ guidance/README.md | 12 +- guidance/how-to/README.md | 14 +- guidance/playbooks/README.md | 6 +- policies/README.md | 14 +- reference/README.md | 10 +- standards/README.md | 14 +- 8 files changed, 237 insertions(+), 27 deletions(-) create mode 100644 .github/instructions/documentation.instructions.md diff --git a/.github/instructions/documentation.instructions.md b/.github/instructions/documentation.instructions.md new file mode 100644 index 000000000..c12d86d85 --- /dev/null +++ b/.github/instructions/documentation.instructions.md @@ -0,0 +1,172 @@ +--- +applyTo: "**/*.md" +--- + +# Documentation guidance + +Use this guidance when creating or updating documentation in this repository. + +## Core principle + +Write documentation around the reader's need. Do not organise or expand content only around ownership, internal structure, or where similar material already exists. + +Use these four documentation modes to keep pages focused and useful: + +- **Tutorials**: teach a newcomer through a safe, successful first experience. +- **How-to guides**: help a reader complete a specific task. +- **Reference**: provide accurate information for lookup. +- **Explanation**: build understanding, context, and judgement. + +A page should usually have one primary mode. If a page must include more than one mode, make the sections clearly distinct and link out to dedicated pages when the content grows. + +## Repository structure + +Keep the current repository structure. + +Use the existing top-level areas as follows: + +- `communities/`: audience, practice, or community landing pages. +- `policies/`: authoritative statements of what must be done. +- `standards/`: authoritative implementation expectations. +- `guidance/how-to/`: task-oriented guides. +- `guidance/playbooks/`: repeatable workflow guidance. +- `guidance/checklists/`: review, assurance, or workflow prompts. +- `guidance/examples/`: concrete examples, labelled by purpose. +- `reference/`: lookup material, templates, roles, and reusable supporting assets. + +This repository has a complex hierarchy. It is acceptable for audience, governance type, and topic area to sit above or alongside these documentation modes, provided each page remains clear about the reader need it serves. + +## Map local document types to documentation modes + +Use this mapping when deciding where content belongs and how it should be written: + +| Local type | Primary documentation mode | Write it as | +| --- | --- | --- | +| Policy | Reference | Authoritative requirements. Keep rationale separate or clearly marked. | +| Standard | Reference | Repeatable implementation expectations. Link to how-to guidance for procedures. | +| Guidance | How-to or explanation | Decide whether the page helps the reader act or understand. | +| Checklist | Reference or how-to | Use reference style for lookup checklists and how-to style for workflow checklists. | +| Example | Tutorial, explanation, or reference | State whether the example teaches, explains, or provides a pattern to copy. | +| Community page | Landing page | Orient an audience and route them to the right material. | + +## Page-purpose guidance + +For new pages, and for substantial edits to existing pages, include a clear purpose near the top when it helps readers choose correctly. + +Prefer this shape: + +```text +Document type: How-to guide +Audience: Delivery team developers +Use this when: you need to deploy a service to a cloud environment +``` + +Use wording that fits the page. The important point is that the page should make clear: + +- what kind of document it is; +- who it is for; +- when to use it. + +## Tutorials + +Create tutorial material only when there is a real learning need. Do not use a tutorial for a general task guide. + +A tutorial should: + +- be learning-oriented; +- be safe for a newcomer; +- have a clear start and end; +- guide the reader to a successful result; +- avoid branching into many options; +- link onward to relevant how-to, reference, and explanation pages. + +## How-to guides + +Use how-to guides for specific tasks. + +A how-to guide should: + +- start from the reader's task; +- use action-oriented headings; +- keep background explanation brief; +- link to policy or reference material instead of repeating it; +- avoid becoming a broad topic overview. + +## Reference material + +Use reference pages for authoritative lookup information. + +Reference material should: + +- be accurate and complete for its scope; +- be structured consistently; +- avoid tutorial-style teaching; +- avoid long explanatory digressions; +- link to explanation pages for rationale where needed. + +Policies and standards are usually reference material. Keep mandatory wording precise and easy to find. + +## Explanation + +Use explanation pages to build understanding. + +Explanation should: + +- explain why something matters; +- provide context, rationale, trade-offs, and judgement; +- avoid step-by-step task instructions unless they are examples in support of the explanation; +- link to how-to guides for action and reference pages for details. + +## Landing pages + +README files and other landing pages should be written for humans, not just as link lists. + +A landing page should: + +- explain the area it covers; +- tell readers when to use each sub-area; +- group links under meaningful headings when there are more than a few items; +- include short introductory text where it improves discoverability; +- link to related areas when the same topic spans communities, policies, standards, guidance, or reference. + +Avoid long flat lists. If a list grows beyond about seven items, group it by user need, lifecycle stage, role, topic, or mandatory versus recommended material. + +## Mixed-purpose pages + +Avoid mixing policy, standard, how-to, reference, and explanation content on one page. + +When an existing page has mixed purposes: + +1. identify the primary reader need; +2. keep the page focused on that need; +3. move or link secondary material to a better page; +4. use a landing page to route readers if several needs must remain visible together. + +Pay particular attention when a page path, title, and content type disagree. Align them where practical. + +## Cross-linking + +Cross-link deliberately because topics often span multiple modes and repository areas. + +For example, a testing topic might need links between: + +- community guidance; +- testing policies; +- testing standards; +- checklists; +- examples. + +Prefer linking over duplicating content. Duplicate only when the repeated text is small, stable, and genuinely helps the reader. + +## Contributor checklist + +Before adding or substantially changing a document, check: + +- Does the page have one clear primary documentation mode? +- Is the page in the right repository area for its local document type? +- Does the heading match the path and purpose? +- Would a reader know when to use this page? +- Is mandatory content separated from advice and explanation? +- Are long lists grouped into smaller meaningful sections? +- Are related policies, standards, guidance, and reference pages linked where useful? +- Have relevant local `README.md` files been updated? diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26c4d03b2..b72390c46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,6 +24,28 @@ Before adding a new document, decide what kind of document it is and place it in - **Checklist**: repeatable review or assurance steps. - **Reference**: supporting information, templates, examples, or background material. +## Mapping for contributors + +When deciding how to shape a page, use the following mapping to keep each document focused on a clear reader need. + +| Local type | Primary documentation mode | Guidance | +| --- | --- | --- | +| Policy | Reference | State authoritative requirements. Keep rationale separate or clearly marked. | +| Standard | Reference | State repeatable implementation expectations. Link to how-to guidance for procedures. | +| Guidance | How-to or explanation | Decide whether the page helps the reader complete a task or understand a topic. | +| Checklist | Reference or how-to | Use reference style for lookup checklists and how-to style for workflow checklists. | +| Example | Tutorial, explanation, or reference | Make clear whether the example teaches, explains, or provides a reusable pattern. | +| Community page | Landing page | Orient an audience and route them to the right policies, standards, guidance, and reference pages. | + +Use these documentation modes when shaping content: + +- **Tutorials** teach a newcomer through a safe, successful first experience. +- **How-to guides** help a reader complete a specific task. +- **Reference** provides accurate information for lookup. +- **Explanation** builds understanding, context, and judgement. + +A page should usually have one primary mode. If a page starts to mix policy, task guidance, reference detail, and explanation, either split it into separate pages or make the sections clearly distinct. + ## Naming rules - folders use `kebab-case` diff --git a/guidance/README.md b/guidance/README.md index 13b2b3870..e2c37ab49 100644 --- a/guidance/README.md +++ b/guidance/README.md @@ -1,10 +1,12 @@ # Guidance -Use the guidance area for practical how-to material, playbooks, checklists, and examples. +Use the guidance area for practical help. Start here when you need to complete a task, follow a repeatable workflow, review work against a checklist, or learn from concrete examples. + +Choose a sub-area based on what you need: ## Areas -- [How-to](./how-to/README.md) -- [Playbooks](./playbooks/README.md) -- [Checklists](./checklists/README.md) -- [Examples](./examples/README.md) +- [How-to](./how-to/README.md) for task-focused guidance when you need to do something specific. +- [Playbooks](./playbooks/README.md) for repeatable workflows that involve several steps or decision points. +- [Checklists](./checklists/README.md) for review, assurance, or readiness prompts. +- [Examples](./examples/README.md) for concrete patterns, sample artefacts, and material to learn from. diff --git a/guidance/how-to/README.md b/guidance/how-to/README.md index 3ddd8e9bb..c359ce328 100644 --- a/guidance/how-to/README.md +++ b/guidance/how-to/README.md @@ -1,9 +1,13 @@ # How-to guidance +Use this area when you need to complete a specific task. These guides should help you get something done without turning into broad topic overviews. + +Choose the area that best matches the task in front of you: + ## Key areas -- [Cloud development](./cloud-development/README.md) -- [GitHub](./github/README.md) -- [Induction](./induction/README.md) -- [Infrastructure as code](./infrastructure-as-code/README.md) -- [Logging](./logging/README.md) +- [Cloud development](./cloud-development/README.md) for delivery tasks related to cloud-hosted applications and services. +- [GitHub](./github/README.md) for repository, pull request, and collaboration tasks in GitHub. +- [Induction](./induction/README.md) for onboarding tasks and first steps in the engineering environment. +- [Infrastructure as code](./infrastructure-as-code/README.md) for infrastructure delivery tasks and working practices. +- [Logging](./logging/README.md) for implementing and operating application logging. diff --git a/guidance/playbooks/README.md b/guidance/playbooks/README.md index efc9353cc..41a30a059 100644 --- a/guidance/playbooks/README.md +++ b/guidance/playbooks/README.md @@ -1,5 +1,9 @@ # Playbooks +Use playbooks when a piece of work follows a repeatable workflow rather than a single task. A playbook should help readers understand the sequence of activities, key decisions, and useful links for completing the work. + +Current playbooks: + ## Key areas -- [Package adoption](./package-adoption/README.md) +- [Package adoption](./package-adoption/README.md) for the workflow used to assess, approve, and introduce packages. diff --git a/policies/README.md b/policies/README.md index 096938de3..c697b6d3a 100644 --- a/policies/README.md +++ b/policies/README.md @@ -1,11 +1,13 @@ # Policies -Use the policies area for mandatory requirements and approved policy statements. +Use the policies area for mandatory requirements and approved policy statements. Start here when you need to know what must be done rather than how to do it. + +Choose the policy area that matches the concern you are working on: ## Areas -- [Engineering](./engineering/README.md) -- [Security](./security/README.md) -- [Testing](./testing/README.md) -- [Data](./data/README.md) -- [Platform](./platform/README.md) +- [Engineering](./engineering/README.md) for delivery practices, code quality, and engineering expectations. +- [Security](./security/README.md) for secure development and related security requirements. +- [Testing](./testing/README.md) for mandatory assurance and defect management requirements. +- [Data](./data/README.md) for data handling, lifecycle, and assurance requirements. +- [Platform](./platform/README.md) for platform, infrastructure, container, and pipeline requirements. diff --git a/reference/README.md b/reference/README.md index 55f75be3e..ff14d5a92 100644 --- a/reference/README.md +++ b/reference/README.md @@ -1,9 +1,11 @@ # Reference -Use the reference area for supporting roles, technology radar material, templates, and other supporting information. +Use the reference area for supporting material that readers may need to look up alongside policies, standards, and guidance. Start here when you need roles, templates, reusable assets, or background reference information. + +Choose an area based on the kind of supporting information you need: ## Areas -- [Roles](./roles/README.md) -- [Technology radar](./technology-radar/README.md) -- [Templates](./templates/README.md) +- [Roles](./roles/README.md) for responsibilities and role-specific context. +- [Technology radar](./technology-radar/README.md) for technology choices, status, and supporting rationale. +- [Templates](./templates/README.md) for reusable document and delivery assets. diff --git a/standards/README.md b/standards/README.md index 714947be6..dcc004613 100644 --- a/standards/README.md +++ b/standards/README.md @@ -1,11 +1,13 @@ # Standards -Use the standards area for implementation expectations and repeatable engineering standards. +Use the standards area for implementation expectations and repeatable engineering standards. Start here when you know a requirement applies and need to understand the expected shape of a good implementation. + +Choose the standards area that best matches the work you are doing: ## Areas -- [Coding](./coding/README.md) -- [Testing](./testing/README.md) -- [Source control](./source-control/README.md) -- [Observability](./observability/README.md) -- [Documentation](./documentation/README.md) +- [Coding](./coding/README.md) for language and code quality standards. +- [Testing](./testing/README.md) for testing implementation expectations. +- [Source control](./source-control/README.md) for branch protection and repository working practices. +- [Observability](./observability/README.md) for logging, monitoring, and observability expectations. +- [Documentation](./documentation/README.md) for documentation standards, naming, and supporting guidance. From 7465e7dba352eb97938b711483f7204201c666e4 Mon Sep 17 00:00:00 2001 From: Martyn Fewtrell Date: Thu, 14 May 2026 11:50:12 +0100 Subject: [PATCH 4/4] Standardize list markers in README.md for consistency Updated list markers in README.md to use consistent Markdown formatting. Changed '-' to '*' and vice versa in relevant sections to align with best practices. No content changes were made. --- communities/quality-assurance/README.md | 34 ++++++++++----------- guidance/how-to/cloud-development/README.md | 6 ++-- guidance/how-to/github/README.md | 6 ++-- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/communities/quality-assurance/README.md b/communities/quality-assurance/README.md index d487eee3f..3cb4e97f0 100644 --- a/communities/quality-assurance/README.md +++ b/communities/quality-assurance/README.md @@ -19,26 +19,26 @@ This area is the community entry point for testing and assurance guidance. If you read nothing else, then read these things: -* Our [Test Strategy](test-strategy.md) contains details of the UKHO approach to testing. -* The [UKHO Delivery Quality Charter](ukho-quality-charter.md) assists delivery teams in adopting practices proven to improve quality of delivery. -* The [Testing policies](../../policies/testing/README.md) explain the mandatory testing requirements. -* The [Testing standards](../../standards/testing/README.md) explain testing-specific implementation expectations. +- Our [Test Strategy](test-strategy.md) contains details of the UKHO approach to testing. +- The [UKHO Delivery Quality Charter](ukho-quality-charter.md) assists delivery teams in adopting practices proven to improve quality of delivery. +- The [Testing policies](../../policies/testing/README.md) explain the mandatory testing requirements. +- The [Testing standards](../../standards/testing/README.md) explain testing-specific implementation expectations. ## Contents -* Process guidance - * [Acceptance criteria](acceptance-criteria.md) - * [BDD reference page](bdd.md) - * [Test strategy](test-strategy.md) - * [Test automation standards](test-code-standards.md) - * [UKHO Delivery Quality Charter](ukho-quality-charter.md) -* Technical testing resources - * [Accessibility](accessibility-testing.md) - * [Exemplar repositories](test-repositories.md) - * [Performance testing checklist](performance-test-checklist.md) - * [Safety assurance](safety-assurance-guidance.md) - * [UI automation](browser-automation.md) - * [Security testing guidance](security-testing-guidance.md) +- Process guidance + - [Acceptance criteria](acceptance-criteria.md) + - [BDD reference page](bdd.md) + - [Test strategy](test-strategy.md) + - [Test automation standards](test-code-standards.md) + - [UKHO Delivery Quality Charter](ukho-quality-charter.md) +- Technical testing resources + - [Accessibility](accessibility-testing.md) + - [Exemplar repositories](test-repositories.md) + - [Performance testing checklist](performance-test-checklist.md) + - [Safety assurance](safety-assurance-guidance.md) + - [UI automation](browser-automation.md) + - [Security testing guidance](security-testing-guidance.md) ## Related areas diff --git a/guidance/how-to/cloud-development/README.md b/guidance/how-to/cloud-development/README.md index 55390ee10..880b3bcb4 100644 --- a/guidance/how-to/cloud-development/README.md +++ b/guidance/how-to/cloud-development/README.md @@ -60,6 +60,6 @@ This policy applies to all software engineering teams and individuals within the ## Related areas -- [Data engineering](../../../communities/data-engineering/README.md) -- [Platform policies](../../../policies/platform/README.md) -- [Observability standards](../../../standards/observability/README.md) +* [Data engineering](../../../communities/data-engineering/README.md) +* [Platform policies](../../../policies/platform/README.md) +* [Observability standards](../../../standards/observability/README.md) diff --git a/guidance/how-to/github/README.md b/guidance/how-to/github/README.md index b762600b7..d0f6b5545 100644 --- a/guidance/how-to/github/README.md +++ b/guidance/how-to/github/README.md @@ -35,9 +35,9 @@ All open repositories must use git and contributions should follow the standard ## Related areas -- [Platform policies](../../../policies/platform/README.md) -- [Source control standards](../../../standards/source-control/README.md) -- [Root contribution guidance](../../../CONTRIBUTING.md) +* [Platform policies](../../../policies/platform/README.md) +* [Source control standards](../../../standards/source-control/README.md) +* [Root contribution guidance](../../../CONTRIBUTING.md) ## Terminology