├── .github └── workflows │ └── markdown-ci.yml ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── catalog-info.yaml ├── mdlint.json ├── package.json ├── quality-assurance ├── Automation-of-SecurityTesting-ZAP.md ├── README.md ├── Security-Testing-Guidance.md ├── Test-Approach-TSR-Reviews.md ├── acceptance-criteria.md ├── accessibility-testing.md ├── automated-api-testing.md ├── bdd.md ├── browser-automation.md ├── desktop-accessibility-testing.md ├── executable-specifications.md ├── exploratory-testing.md ├── http-api-mocking-tools.md ├── images │ ├── bdd_tree_swing.png │ ├── dicovery_formulation_automation.png │ ├── example_mapping.png │ ├── test-pyramid.png │ ├── the_test_pyramid.png │ ├── the_test_pyramid_updated.png │ ├── zap2.jpg │ ├── zap3.jpg │ ├── zap4.jpg │ ├── zap5.jpg │ ├── zap6.jpg │ ├── zap7.jpg │ ├── zap8.jpg │ └── zapazuresetup.jpg ├── manual-test-scripts.md ├── microservice-testing.md ├── performance-test-checklist.md ├── safety-assurance-guidance.md ├── test-code-standards.md ├── test-policy.md ├── test-repositories.md ├── test-strategy.md ├── ukho-quality-charter.md ├── user-acceptance-testing.md └── web-accessibility-testing.md ├── security ├── ManagingSecurityConcerns │ ├── CvssScoringMetrics.md │ └── ManagingSecurityConcerns.md ├── SecurityChampions │ └── SecurityChampionResponsibilities.md └── ThreatModelling │ └── ThreatModelling.md ├── software-engineering-policies ├── CONTRIBUTING.md ├── CloudDevelopment │ ├── CloudFirst.md │ ├── Containers.md │ ├── DataUse.md │ ├── Deployment.md │ ├── DisasterRecoveryBusinessContinuity.md │ ├── General.md │ ├── LoggingAndMonitoring.md │ ├── PilotsLicense.md │ ├── README.md │ ├── Tagging.md │ ├── Users.md │ └── images │ │ └── Difference-between-anonymization-and-pseudonymization.png ├── CodeCopyright │ └── CodeCopyrightPolicy.md ├── CodeGenerationTools │ └── CodeGenerationToolsPolicy.md ├── CodeReuse │ └── CodeReusePolicy.md ├── CodeReview │ └── CodeReviewPolicy.md ├── CodingStandards │ ├── CssCodingStandards.md │ ├── DotNetCodingStandards.md │ ├── HtmlCodingStandards.md │ ├── JavascriptCodingStandards.md │ ├── PythonCodingStandards.md │ └── README.md ├── Containers │ ├── ContainerBestPractices.md │ └── ContainerPolicy.md ├── DefectManagement │ └── DefectManagementPolicy.md ├── FrontEnd │ └── FrontEndPolicy.md ├── InclusiveLanguage │ └── InclusiveLanguagePolicy.md ├── Induction │ ├── LeadDeveloperInduction.md │ └── SettingUpYourMSDN.md ├── InfrastructureAsCode │ └── terraform.md ├── Logging │ └── LoggingPolicy.md ├── NFRs │ └── NFRPolicy.md ├── NamingConventions │ └── NamingConventions.md ├── OpenSourceContribution │ ├── OpenSourceContributionPolicy.md │ └── OpenSourceGovernanceChecklist.md ├── OpenSourceUse │ └── OpenSourceUsePolicy.md ├── PackageAdoption │ ├── PackageAdoptionChecklist.md │ ├── PackageAdoptionGuidance.md │ └── PackageAdoptionPolicy.md ├── PairProgramming │ └── PairProgrammingPolicy.md ├── Pipelines │ └── Baseline_Policy.md ├── PublicRadar.csv ├── README.md ├── Resources │ ├── baseline-diagram.png │ └── control-options.png ├── SecureDevelopment │ └── SecureDevelopmentPolicy.md ├── SourceControl │ ├── AzDoBranchProtection.md │ ├── GitBranchProtectionPolicy.md │ ├── RepositorySetupPolicy.md │ └── SourceControlPolicy.md ├── SystemDocumentation │ └── SystemDocumentationPolicy.md ├── TechnicalDebt │ ├── Example_TD_V4.png │ ├── Porfolio_TD_V1.png │ ├── TechnicalDebtMonitoring.md │ ├── TechnicalDebtPolicy.md │ └── dashboard_TD_V1.png ├── TechnologyGovernance │ └── TechnologyGovernance.md ├── ThirdPartyLicensing │ ├── ThirdPartyLicensingGuidance.md │ └── ThirdPartyLicensingPolicy.md ├── UnitTesting │ └── UnitTestingPolicy.md ├── development-principles.md ├── engineering-team.md └── observability │ └── observability_policy.md ├── software-engineering └── roles │ └── principal-developer.md └── using-github ├── creating-a-contributing-file.md ├── creating-a-readme-file.md ├── migrating-to-github.md ├── pull-request-details.md └── readme.md /.github/workflows/markdown-ci.yml: -------------------------------------------------------------------------------- 1 | name: Markdown CI 2 | 3 | on: 4 | push: 5 | branches: [ main, master ] 6 | pull_request: 7 | branches: [ main, master ] 8 | 9 | jobs: 10 | build: 11 | runs-on: ubuntu-latest 12 | 13 | steps: 14 | - uses: actions/checkout@v3 15 | - uses: actions/setup-node@v3 16 | with: 17 | node-version: '12' 18 | - run: npm install alex 19 | 20 | - name: Alex.js 21 | run: npm run test-alex 22 | 23 | - name: Markdown lint 24 | if: success() || failure() 25 | uses: nosborn/github-action-markdown-cli@v1.1.1 26 | with: 27 | files: . 28 | ignore_files: node_modules 29 | config_file: "mdlint.json" 30 | 31 | # - name: Check for 404 links 32 | # if: success() || failure() 33 | # uses: restqa/404-links@1.0.1 34 | # with: 35 | # path: . 36 | # ignore: 'https://cucumber.io,https://docs.data.ukho.gov.uk,https://github.com,https://en.wikipedia.org,https://www.nationalarchives.gov.uk' 37 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site/ 2 | 3 | # IDEA config files 4 | .idea/ 5 | /quality-assurance/.vs 6 | /.vs -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to UKHO Docs 2 | 3 | Firstly, thank you for taking the time to contribute! We appreciate it as this is not the most exciting or glamorous of topics. 4 | 5 | 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. 6 | 7 | ## Questions 8 | 9 | If you have any questions, please open an issue. 10 | 11 | ## Improvements 12 | 13 | If you have any improvements (things being poorly worded, misspelt, unclear, tweaks) please make a pull request. During the pull request review we will check to ensure your improvements have not changed the meaning of the guidance. 14 | 15 | ## Changes 16 | 17 | If you would like to make changes (disagreements about the current guidance, substantial adding of new guidance) the best approach is to open an issue with the details/ideas so we can discuss the changes before a pull request is made. If no issue is made before a pull request we will still consider it, however there is chance the your effort is wasted if we don't accept your pull request :( 18 | 19 | ## Contact 20 | 21 | Nev Brown @nevillejrbrown 22 | Greg Zealley @gregzealley 23 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2021 UK Hydrographic Office 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Software Engineering at the UKHO 2 | 3 | This repository contains documentation about digital delivery teams, their behaviours and processes and our engineers at the UKHO. 4 | 5 | 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. 6 | 7 | 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. 8 | 9 | ## How we work 10 | 11 | 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. 12 | 13 | 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. 14 | 15 | We strive to automate as much as possible: [testing](./quality-assurance/test-strategy.md), builds, deployments use the latest automation tools available. 16 | 17 | We actively look to pay down [technical debt](./software-engineering-policies/TechnicalDebt/TechnicalDebtGuidance.md). 18 | 19 | ## Our community 20 | 21 | We encourage the formation of specialist communities to support our interests and our work. 22 | 23 | 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. 24 | 25 | 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. 26 | 27 | We also have many other communities of interest covering such things as Accessibility, Testing, UX, Azure, AWS and .Net. 28 | 29 | ## Balance 30 | 31 | 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. 32 | -------------------------------------------------------------------------------- /catalog-info.yaml: -------------------------------------------------------------------------------- 1 | apiVersion: backstage.io/v1alpha1 2 | kind: Component 3 | metadata: 4 | name: docs 5 | description: UKHO digital documentation 6 | annotations: 7 | github.com/project-slug: ukho/docs 8 | backstage.io/techdocs-ref: url:https://github.com/ukho/docs 9 | spec: 10 | type: documentation 11 | owner: team-leads 12 | lifecycle: beta 13 | -------------------------------------------------------------------------------- /mdlint.json: -------------------------------------------------------------------------------- 1 | { 2 | "comment": "Relaxed rules", 3 | 4 | "default": true, 5 | "whitespace": false, 6 | "line_length": false, 7 | "ul-start-left": false, 8 | "ul-indent": false, 9 | "no-inline-html": false, 10 | "no-bare-urls": false, 11 | "fenced-code-language": false, 12 | "first-line-h1": false, 13 | "no-duplicate-heading": false 14 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "scripts": { 3 | "test-alex": "alex" 4 | }, 5 | "dependencies": { 6 | "alex": "^9.0.1" 7 | }, 8 | "alex": { 9 | "noBinary": false, 10 | "profanitySureness": 2, 11 | "deny": [ 12 | "blacklist", 13 | "blacklisted", 14 | "blacklisting", 15 | "whitelist", 16 | "whitelisting", 17 | "whitelisted", 18 | "whitespace", 19 | "sanity-check", 20 | "dummy" 21 | ] 22 | } 23 | } -------------------------------------------------------------------------------- /quality-assurance/Automation-of-SecurityTesting-ZAP.md: -------------------------------------------------------------------------------- 1 | # Installation of ZAP into Pipeline 2 | 3 | The ZAP tool can be installed within the azure pipeline using the following step: 4 | 5 | 1. Download the following file and place it in your desired repo 6 | 'OWASPToNUnit3.xslt'. This file is needed to convert OWASP ZAP Security Test result XML file to publish results in Azure DevOps. 7 | Here is the link to the git repo for the file [Github repo for OWASPToNUnit3](https://dev.azure.com/francislacroix/_git/CodeShare?path=/OWASPBlog/OWASPToNUnit3.xslt) 8 | 9 | 1. Create a new pipeline in Azure DevOps 10 | 11 | Go to the Pipeline section within the azure DevOps and select the new pipeline option 12 | 13 | 1. Repository selection 14 | 15 | The next stage is to select a repo for the pipeline, in our case we selected GIT 16 | 17 | - The repo we setup was - UKHO/Gridded-Bathymetry-Service-UI 18 | - Setting up the branch we need to trigger off was => refs/heads/OwaspZAPSecurityTests 19 | - Set the clean option to TRUE 20 | - Set clean options to SOURCE 21 | - Tag sources are set to NEVER 22 | - And select the Report build status 23 | 24 | 1. Initial setup for the Agent Job in Azure pipeline 25 | 26 | ![Azure Agent setup](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zapazuresetup.jpg) 27 | 28 | 1. The setup for the installation for the Docker 29 | 30 | ![installing Azure docker setup](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap2.jpg) 31 | 32 | 1. Next stage is to setup the test using a BASH script 33 | 34 | ![setup tests using Bash script](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap3.jpg) 35 | 36 | > Within the script section of the page then you will need to add similar text to – 37 | chmod -R 777 ./ 38 | 39 | > docker run --name ZapContainer -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-stable zap-full-scan.py -t https://gbsstorageaccountdev.z33.web.core.windows.net/ -g gen.conf -x OWASP-ZAP-Report.xml -r scan-report.html 40 | 41 | > docker cp ZapContainer:/zap/wrk/OWASP-ZAP-Report.xml $(System.DefaultWorkingDirectory)/AutoTests/OWASP-ZAP-Report.xml 42 | 43 | > docker rm /ZapContainer 44 | true 45 | 46 | 1. The next stage is to setup the conversion into NUnit reports using a PowerShell script 47 | 48 | ![Convert into NUnit](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap4.jpg) 49 | 50 | > Now setup the ZAP reporting, this is needed to view the results of performing the security checks on the application. Ensure that you have entered the following text in the scripting section: - 51 | 52 | > $XslPath = "$(System.DefaultWorkingDirectory)/AutoTests/OWASPToNUnit3.xslt" 53 | > $XmlInputPath = "$(System.DefaultWorkingDirectory)/AutoTests/OWASP-ZAP-Report.xml" 54 | > $XmlOutputPath = "$(System.DefaultWorkingDirectory)/Converted-OWASP-ZAP-Report-$(Build.BuildNumber).xml" 55 | > $XslTransform = New-Object System.Xml.Xsl.XslCompiledTransform 56 | > $XslTransform.Load($XslPath) 57 | > $XslTransform.Transform($XmlInputPath, $XmlOutputPath) 58 | 59 | > Get-Content $XmlOutputPath 60 | 61 | 1. The last stage is to publish the results 62 | 63 | ![publishing the results](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap5.jpg) 64 | 65 | > This stage is the final one for configuration an Agent Job and ensures that you publish the results. 66 | 67 | 1. Setting up API testing for ZAP using BASH script 68 | 69 | ![setup API tests using Bash script](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap6.jpg) 70 | 71 | > The above illustrates the 3rd step in configuring the agent to test API’s. this is setting up the Bash Script. You must enter the text into the script section as- 72 | chmod -R 777 ./ 73 | 74 | > docker run --name ZapContainer -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-weekly zap-api-scan.py -t [your-api-url] -f openapi -g api-scan.conf -x OWASP-ZAP-Report.xml -r api-scan-report.html 75 | 76 | > docker cp ZapContainer:/zap/wrk/OWASP-ZAP-Report.xml $(System.DefaultWorkingDirectory)/AutoTests/OWASP-ZAP-Report.xml 77 | 78 | > docker rm /ZapContainer 79 | true 80 | 81 | 1. Adding PowerShell script to convert report to NUnit 82 | 83 | ![Powershell to NUnit report](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap7.jpg) 84 | 85 | > The next stage is to convert the ZAP report into an Nunit report. 86 | Display name - this can be anything you like that is meaningful 87 | Type and the Script – these need to be inline 88 | The text in the script box should be :- 89 | $XslPath = "$($Env:SYSTEM_DEFAULTWORKINGDIRECTORY)/_Quality/SecurityTesting/OWASPToNUnit3.xslt" 90 | $XmlInputPath = "$($Env:SYSTEM_DEFAULTWORKINGDIRECTORY)/OWASP-ZAP-Report.xml" 91 | $XmlOutputPath = "$($Env:SYSTEM_DEFAULTWORKINGDIRECTORY)/Converted-OWASP-ZAP-Report.xml" 92 | $XslTransform = New-Object System.Xml.Xsl.XslCompiledTransform 93 | $XslTransform.Load($XslPath) 94 | $XslTransform.Transform($XmlInputPath, $XmlOutputPath) 95 | 96 | 1. Publish the reports 97 | 98 | ![Publish the Report](https://github.com/UKHO/docs/blob/Security-test-automation/quality-assurance/images/zap8.jpg) 99 | 100 | The final stage is to publish the report 101 | -------------------------------------------------------------------------------- /quality-assurance/README.md: -------------------------------------------------------------------------------- 1 | # Quality assurance at the UKHO 2 | 3 | Welcome to Quality Assurance at the UKHO. Here you will find both process and technical guidance for testers, developers and everyone else involved in creating software at the UKHO. 4 | 5 | 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. 6 | 7 | ## Where to start 8 | 9 | If you read nothing else, then read these things: 10 | 11 | * Our [Test Strategy](test-strategy.md) contains details of the UKHO approach to testing. 12 | * The [UKHO Delivery Quality Charter](ukho-quality-charter.md) assists delivery teams in adopting practices proven to improve quality of delivery. 13 | 14 | ## Contents 15 | 16 | * Process guidance 17 | * [Acceptance criteria](acceptance-criteria.md) 18 | * [BDD reference page](bdd.md) 19 | * [Test strategy](test-strategy.md) 20 | * [Test automation standards](test-code-standards.md) 21 | * [UKHO Delivery Quality Charter](ukho-quality-charter.md) 22 | * Technical testing resources 23 | * [Accessibility](accessibility-testing.md) 24 | * [Exemplar repositories](test-repositories.md) 25 | * [Performance testing checklist](performance-test-checklist.md) 26 | * [Safety assurance](safety-assurance-guidance.md) 27 | * [UI automation](browser-automation.md) 28 | * [Security testing Guidance](Security-Testing-Guidance.md) 29 | -------------------------------------------------------------------------------- /quality-assurance/Test-Approach-TSR-Reviews.md: -------------------------------------------------------------------------------- 1 | This page documents the role of a Test Lead in reviewing Test Approach / Test Summary Report documents. 2 | 3 | A Test Lead should review all these documents. In doing so, they are assuring the following: 4 | 5 | ## Test Approach 6 | 7 | - Has the form been completed as far as possible? 8 | - Is the approach in line with the test policies? 9 | - Has the approach been agreed with appropriate people? 10 | - Does the tester need support from outside the team? 11 | 12 | ## Test Summary Report 13 | 14 | - Has the testing been done according to the agreed approach? 15 | - Have appropriate people reviewed the testing (from the team and other SMEs)? 16 | - Is testing recorded, outstanding risks and defects approved etc.? 17 | - Is testware usable in future work? 18 | 19 | Test Leads do not review individual tests. They are not experts in the system so can’t take a detailed view on coverage. They also do not make the decision to go live; the document provides key evidence to inform that decision. 20 | 21 | The responsibility for testing the product properly sits with the delivery team. This process is facilitated by the team’s tester, but all team members need to understand and contribute. 22 | 23 | 24 | 25 | 26 | -------------------------------------------------------------------------------- /quality-assurance/acceptance-criteria.md: -------------------------------------------------------------------------------- 1 | # Acceptance Criteria Guidance 2 | 3 | This page provides tips on writing effective acceptance criteria (AC). 4 | 5 | ## What is Acceptance Criteria 6 | 7 | > Conditions that a software product must satisfy to be accepted by a user, customer or other stakeholder. 8 | > They are confirmation that the requirements captured in the description have been achieved, and used as part 9 | > of the test criteria also 10 | 11 | ## Why write good Acceptance Criteria 12 | 13 | To ensure all members of a team have a shared understanding of the requirements of the stories they are developing and what needs to be tested 14 | in order to confirm that the story is DONE 15 | 16 | ## How do I know I am doing it right 17 | 18 | 1. The whole team is involved in the creation and refinement of AC 19 | 1. they should be clear and unambigious to ensure clarity 20 | 1. AC is recorded and agreed before a user story are played 21 | 1. Every user story has at least 1 AC - too many ACs? Split the story 22 | 1. All criteria are independently testable with a clear pass / fail outcome 23 | 1. Non-functional criteria is included where applicable 24 | 25 | ## How to generate good Acceptance Criteria 26 | 27 | 1. Use Example Mapping sessions - [Example Mapping as part of BDD](bdd.md) 28 | 1. Record it using Gherkin scenario-orientated syntax - “Given...When...Then...” 29 | 1. Gherkin is behaviour driven and reflects the users flow for a single activity, so they are not intended to depict more than one set of actions in terms of the behaviours. See example given below 30 | 31 | 32 | > example of what not to do 33 | 34 | > 1. **Given** the user have entered data 35 | > 2. **And** they have completed all the mandatory fields 36 | > 3. **when** then submit / click (complete a specific action) 37 | > 4. **Then** they will be presented with the expected results 38 | > 5. **When** the user clicks the next button 39 | > 6. **Then** confirm the next set of results 40 | 41 | 42 | -------------------------------------------------------------------------------- /quality-assurance/accessibility-testing.md: -------------------------------------------------------------------------------- 1 | # Accessibility Testing 2 | 3 | ## Quick links - how to test for accessibility 4 | 5 | To learn how to test accessibility in your web service project read the [UKHO web accessibility testing](web-accessibility-testing.md) page. For desktop application projects read the [UKHO desktop accessibility testing](desktop-accessibility-testing.md). 6 | 7 | ## What is accessibility 8 | 9 | Accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. More specifically, people can perceive, understand, navigate, and interact with the web. It encompasses all disabilities that affect access to the web, including 10 | 11 | * auditory 12 | * cognitive 13 | * neurological 14 | * physical 15 | * speech 16 | * visual 17 | 18 | Accessibility also benefits people without disabilities, like people with changing abilities due to ageing and people with “temporary disabilities” such as 19 | 20 | * a broken arm 21 | * lost glasses 22 | * people using a slow Internet connection 23 | * people who have limited or expensive bandwidth 24 | 25 | ## Legal requirements 26 | 27 | We have a legal obligation to make websites and mobile applications conform (as a minimum) to **WCAG 2.1 AA** 28 | 29 | The accessibility regulations came into force for public sector bodies on 23 September 2018. They say you must make your website or mobile app more accessible by making it ‘perceivable, operable, understandable and robust’. You need to include and update an accessibility statement on your website. 30 | 31 | The full name of the accessibility regulations is the Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018. 32 | 33 | The accessibility regulations build on your existing obligations to people who have a disability under the Equality Act 2010 (or the Disability Discrimination Act 1995 in Northern Ireland). These say that all UK service providers must consider ‘reasonable adjustments’ for disabled people. 34 | 35 | * [Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018](https://www.legislation.gov.uk/uksi/2018/952/contents/made) 36 | * [Equality Act 2010](https://www.legislation.gov.uk/ukpga/2010/15/contents) 37 | * [Understanding accessibility requirements for public sector bodies](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps) 38 | * [Meeting government accessibility requirements](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction#meeting-government-accessibility-requirements) 39 | 40 | ## WCAG (Web Content Accessibility Guidelines) 41 | 42 | The Web Content Accessibility Guidelines (known as WCAG 2.1) are an internationally recognised set of recommendations for improving accessibility. 43 | 44 | WCAG 2.1 is based on 4 design principles: 45 | 46 | * perceivable 47 | * operable 48 | * understandable 49 | * robust 50 | 51 | It is the WCAG recommendations that are used to verify whether a website or mobile app is accessible. 52 | 53 | Read more about [understanding WCAG](https://www.gov.uk/service-manual/helping-people-to-use-your-service/understanding-wcag). 54 | 55 | View the [list of WCAG requirements](https://www.w3.org/WAI/WCAG21/quickref/) (this can be filtered on A level). 56 | 57 | ## Developing your service for accessibility 58 | 59 | Read [how to make your service accessible](https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction) throughout the development and maintainance of your service. 60 | 61 | To understand how to test accessibility read either: 62 | 63 | * [UKHO web accessibility testing](web-accessibility-testing.md) 64 | * [UKHO desktop accessibility testing](desktop-accessibility-testing.md) 65 | 66 | ## Incorporating accessibility testing into the Definition of Done 67 | 68 | We can’t deploy code which is not accessible so if it’s not accessible it’s not done. Including accessibility in your team's Definition of Done is a great way to ensure the requirements are met. 69 | 70 | Accessibility considerations to be included in a Definition of Done include: 71 | 72 | * Code quality 73 | * Usability 74 | * Screen readers 75 | * Screen magnifiers 76 | * Voice control 77 | 78 | See [a detailed example definition of done](https://github.com/hmrc/accessibility/blob/master/docs/definition-of-done.md) that contains examples of these. 79 | 80 | ## Accessibility Statement 81 | 82 | You must produce a bespoke accessibility statement for your service that details how accessible it is and any areas that aren't. See an example UK Government (Universal Credit) [accessibility statement](https://www.universal-credit.service.gov.uk/accessibility-statement). 83 | 84 | Read more about [publishing your accessibility statement](https://www.gov.uk/guidance/make-your-website-or-app-accessible-and-publish-an-accessibility-statement#publish-your-accessibility-statement). 85 | 86 | The gov.uk resource also have a [template accessibility statement](https://www.gov.uk/government/publications/sample-accessibility-statement/sample-accessibility-statement-for-a-fictional-public-sector-website) and there is also an [accessibility statement generator](https://www.w3.org/WAI/planning/statements/generator/#create) that can be used. 87 | -------------------------------------------------------------------------------- /quality-assurance/automated-api-testing.md: -------------------------------------------------------------------------------- 1 | # Automated API Testing Policy Document 2 | 3 | ## Purpose 4 | 5 | This document establishes the policy for the automated testing of .NET APIs. It delineates the approved technologies, clients and processes for API integration tests. 6 | 7 | ## Scope 8 | 9 | This policy is applicable to all teams involved in API development and testing within the organization. 10 | 11 | ## Testing Methodology 12 | 13 | ### Technology 14 | 15 | The standard language for developing APIs at UKHO is C#. Therefore it is expected that automated integration/API tests will also be created using C# (please note this does not apply to performance testing). 16 | 17 | #### Approved Clients 18 | 19 | Currently there are two clients that have been approved for use when writing automated tests for APIs. 20 | 21 | 1. [HttpClient](https://learn.microsoft.com/en-us/dotnet/fundamentals/networking/http/httpclient) - Built into .NET, also used in `WebApplicationFactory` 22 | 2. [RestSharp](https://restsharp.dev/intro.html#introduction) - Third party Nuget package. 23 | 24 | ### Integration Testing with `WebApplicationFactory` 25 | 26 | Where possible [WebApplicationFactory](https://learn.microsoft.com/en-us/aspnet/core/test/integration-tests?view=aspnetcore-8.0) should be used for conducting integration tests. `WebApplicationFactory` creates a test server hosting the application under test, allowing for a controlled, isolated testing environment. 27 | 28 | #### Guidelines for `WebApplicationFactory` Usage 29 | 30 | - **Business Logic Verification** - Tests that verify business logic are ideal candidates for `WebApplicationFactory`. 31 | - **Real Database Integration** - When applicable, integration tests should interface with a real relational database rather than an in-memory database to capture the full spectrum of interactions and potential issues. Suitable examples include a LocalSQLDB or a SQL database provisioned in a Docker container. 32 | - **External Dependencies** - External services can be mocked to isolate the API under test. 33 | - **Consistency and Reliability** - Tests should be consistent and not dependent on external environments. 34 | - **Continuous Integration (CI)** - These tests should be integrated into the CI pipeline. 35 | 36 | An example of using WebApplicationFactory with NUnit can be found [here](https://github.com/UKHO/.NET-Guild/blob/main/CleanArchitectueExample/tests/TestScribe.Api.Tests.Integration/WebApplicationFactoryTests/CreateTestSuiteTests.cs) 37 | 38 | ### Testing with Deployed Instances 39 | 40 | Testing against deployed instances is reserved for: 41 | 42 | #### Legacy Applications 43 | 44 | Some legacy applications may not be suitable to test with `WebApplicationFactory` due to out of support frameworks or dependencies. 45 | 46 | #### Security Testing 47 | 48 | - **Authentication and Authorization** - Tests should confirm that security measures should be conducted in a production-like environment. 49 | 50 | #### Safety and Compliance Testing 51 | 52 | - **Safety Compliance** - Some APIs will have safety requirements that arise from safety modeling, these tests may need to be run against a deployed production-like environment in order to meet the safety requirements. 53 | - **Disaster Recovery** - The APIs disaster recovery mechanisms must be tested in a deployed environment. 54 | 55 | #### Performance and Load Testing 56 | 57 | Note that the preferred technology for Performance/Load testing APIs is K6. Please see [performance testing checklist](https://github.com/UKHO/docs/blob/main/quality-assurance/performance-test-checklist.md) for more info. 58 | 59 | 60 | -------------------------------------------------------------------------------- /quality-assurance/bdd.md: -------------------------------------------------------------------------------- 1 | # Behaviour Driven Development (BDD) 2 | 3 | ## What is BDD 4 | 5 | > "An approach that enhances communication between stakeholders and project team members by expressing product needs as concrete examples" 6 | 7 | BDD: 8 | 9 | * Is a **process** to enable the entire team to better understand stories before they are played 10 | * Enables structured **collaboration** between Product Owners (proxy for the customer), developers and testers to gain an agreed understanding 11 | * Uses **rules and examples** to illustrate this understanding 12 | 13 | BDD is NOT: 14 | 15 | * Testing 16 | * Gherkin 17 | * SpecFlow or Cucumber 18 | * Just automated tests (tests are a downstream benefit) 19 | 20 | ## Benefits of BDD 21 | 22 | * Creates a shared understanding in the team of user requirements 23 | * Ensures all perspectives are considered when defining requirements 24 | * Produces better software that matches user needs first time 25 | 26 | ![bdd tree swing](images/bdd_tree_swing.png) 27 | 28 | ## Stages of BDD 29 | 30 | ![dicovery formulation automation](images/dicovery_formulation_automation.png) 31 | 32 | ## How a team can apply BDD 33 | 34 | ### Discovery 35 | 36 | * The customer representative brings requirements to the team as user stories (PBIs) 37 | * The [Example Mapping technique](#example-mapping) is applied to these stories either by the whole team or a "Three Amigos" subset 38 | * This will create rules and examples that illustrate an understanding of the story 39 | 40 | ### Formulation 41 | 42 | * Examples can be formulated into Gherkin and documented in the [acceptance criteria](acceptance-criteria.md) 43 | 44 | ### Automation 45 | 46 | * Derive automated tests from the Gherkin (this does not have to involve putting the Gherkin into SpecFlow/Cucumber) 47 | 48 | ## Example Mapping 49 | 50 | Example Mapping is a structured technique to drive out understanding of user requirements. 51 | 52 | Example Mapping sessions can involve the whole team, or just the "Three Amigos" (Developer, Tester, Product Owner). It is important that all perspectives in the team are involved. 53 | 54 | ### Approach 55 | 56 | 1. A story is created by the customer representative and presented to the group. 57 | 1. The group discuss the story and determine rules that clarify the purpose of the story. 58 | 1. Examples are created by the group to demonstrate the understanding of the rules. 59 | 1. When creating examples it may become clear that further rules are needed. 60 | 1. When there are lots of rules this may indicate the story is too big and should be split. 61 | 1. Any questions that cannot be answered in the session should be recorded and answered subsequently. 62 | 1. If there are lots of questions this may indicate the story is not understood and needs to go back to the customer. 63 | 64 | ![Example Mapping](images/example_mapping.png) 65 | 66 | ## Resources 67 | 68 | ### Books 69 | 70 | * Discovery: Explore behaviour using examples - Gáspár Nagy and Seb Rose 71 | ([Amazon link](https://www.amazon.co.uk/Discovery-Explore-behaviour-using-examples/dp/1983591254)) 72 | * Formulation: Document examples with Given/When/Then - Seb Rose and Gáspár Nagy 73 | ([Amazon link](https://www.amazon.co.uk/gp/product/B093N4C2C2)) 74 | * BDD in Action: Behaviour-driven development for the whole software lifecycle - John Ferguson Smart 75 | ([Amazon link](https://www.amazon.co.uk/BDD-Action-Behavior-driven-development-lifecycle/dp/161729165X)) 76 | 77 | ### Online resources 78 | 79 | * [Example Mapping by Gáspár Nagy](http://gasparnagy.com/2019/05/divide-conquer-a-la-bdd-story-rule-scenario/) 80 | * [Another description of Example Mapping by Matt Wynne](https://cucumber.io/blog/example-mapping-introduction/) 81 | * [Writing better Gherkin scenarios](http://gasparnagy.com/2019/05/clean-up-bad-bdd-scenarios/) 82 | * [Gherkin - keeping your scenarios BRIEF](https://cucumber.io/blog/keep-your-scenarios-brief/) 83 | * [How writing good Gherkin enables better automation](http://angiejones.tech/writing-good-gherkin-enables-good-test-automation/) 84 | * [How to facilitate an Example Mapping session](http://gasparnagy.com/2019/04/example-mapping-the-good-enough-facilitator/) 85 | -------------------------------------------------------------------------------- /quality-assurance/desktop-accessibility-testing.md: -------------------------------------------------------------------------------- 1 | # How to test a desktop app for Accessibility 2 | 3 | ## Overview 4 | 5 | Desktop apps do not have to adhere to the WCAG requirements that web apps have to. However, the app must still be accessible. There is a W3C working group looking into applying WCAG standards to other forms of ICT. 6 | 7 | Read the [Guidance on Applying WCAG 2.0 to Non-Web Information and Communications Technologies (WCAG2ICT)](https://www.w3.org/WAI/standards-guidelines/wcag/non-web-ict/). 8 | 9 | Microsoft have a [checklist for ensuring a Windows App is accessible](https://docs.microsoft.com/en-us/windows/apps/design/accessibility/accessibility-checklist). 10 | 11 | When testing for accessibility you will need to include the following in your approach: 12 | 13 | * Use of accessibility test tooling 14 | * Manual testing using a keyboard only 15 | * Manual testing using screen readers 16 | * Manual testing using screen magnifiers 17 | 18 | Note that automated testing as part of a CI/CD pipeline will not be possible. 19 | 20 | ## Test Approach 21 | 22 | 1. Manual testing using an accessibility tool 23 | 1. Manual testing using assistive technologies 24 | 25 | This is an older blog from Microsoft but describes a [good test approach using standard tools](https://blogs.windows.com/windowsdeveloper/2014/03/25/testing-for-accessibility-in-windows-store-apps/). Note that Accessibility Insights is now recommended over AccChecker. 26 | 27 | This is another more recent blog from Microsoft on [accessibility testing a Windows App](https://docs.microsoft.com/en-us/windows/apps/design/accessibility/accessibility-testing). 28 | 29 | ### Accessibility Desktop Test Tools 30 | 31 | * [Microsoft Accessibility Insights for Windows](https://accessibilityinsights.io/docs/en/windows/overview/) 32 | * [Colour Contrast Analyser](https://www.tpgi.com/color-contrast-checker/) 33 | 34 | ### Keyboard only 35 | 36 | See section in [UKHO web accessibility testing](web-accessibility-testing.md#keyboard-only). 37 | 38 | ### Screen Readers 39 | 40 | See section in [UKHO web accessibility testing](web-accessibility-testing.md#screen-readers). 41 | 42 | ### Screen Magnifiers 43 | 44 | See section in [UKHO web accessibility testing](web-accessibility-testing.md#screen-magnifiers). 45 | -------------------------------------------------------------------------------- /quality-assurance/executable-specifications.md: -------------------------------------------------------------------------------- 1 | # Executable Specifications 2 | 3 | ## Background 4 | 5 | An executable specification is an expression of business requirements, usually in a language that resembles prose, which can be executed as automated tests. [Reqnroll](https://reqnroll.net/), which is a fork of Specflow is an example. This uses a 'Given - When - Then' syntax, which is the most common form of executable specification. 6 | 7 | ## When to use executable specifications 8 | 9 | The downside of executable specifications is that they add an extra technology plus a layer of mapping code to a project. In theory this is offset by the advantage that tests can be created in collaboration with business users as part of a [BDD](./bdd.md) process. It is therefore our policy that an executable specification like Specflow should NOT be used except as part of a BDD process. If a BDD process has not been used, it usually better to express the intent of tests by naming them well and making them easy to read. 10 | 11 | ## Technology 12 | 13 | Specflow is no longer a supported technology. We should take the opportunity to remove it from our code where appropriate, either by replacing the specification layer entirely, or migrating it to [Reqnroll](https://reqnroll.net/). 14 | -------------------------------------------------------------------------------- /quality-assurance/exploratory-testing.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | Exploratory testing is a software test approach which often described as simultaneous learning and test execution. Cem Kaner, coined this term in 1984 and describes it as "a style of software testing that emphasizes the personal freedom and responsibility of the individual tester to continually optimize the quality of his/her work by treating test-related learning, test design, test execution, and test result interpretation as mutually supportive activities that run in parallel throughout the project." (Testing) 4 | 5 | ## Types of Exploratory Testing 6 | 7 | ### Freestyle Exploratory Testing 8 | 9 | This is an approach where the tester can go through the Application Under Test quickly, investigate defects or do a quick smoke test. 10 | 11 | ### Scenario-based Exploratory Testing 12 | 13 | Real user scenarios serve as the foundation for this type of exploratory testing. The application is examined by testers in all possible ways to accommodate each scenario. To ensure complete test coverage, the goal is to test as many scenarios as possible. 14 | 15 | ### Strategy-based Exploratory Testing 16 | 17 | This approach is often taken when testers are familiar with the application/system under test. It uses various test techniques like BVA, ECP and risk-based to identify deviations. 18 | 19 | ## Benefits of Exploratory testing 20 | 21 | - It offers prompt feedback during the initial stages of development. 22 | - Exploratory testing is appropriate for testing new features during iterative application development, while automation testing concentrates on regression and backward compatibility testing. 23 | - Exploratory testing is ideal for testing new requirements within constrained timeframes when project requirements are unstable. This is because getting outcomes quickly and effectively is the main goal here. 24 | - It finds a diverse range of defects. 25 | 26 | ## Phases of Exploratory testing 27 | 28 | ### Classify defects 29 | 30 | - Categorise the common deviations/defects that were present in previous projects. 31 | - Analyse the root cause of the deviations 32 | 33 | ### Create Test Charter 34 | 35 | - Test charter should include 36 | - Who will be testing 37 | - Purpose, actors, setup 38 | - Test Ideas & Test data 39 | - What scenarios to test and the expected results 40 | - How it can be tested 41 | - Which part of the application/system to explore? 42 | 43 | A sample test charter can be found [here](https://www.tmap.net/sites/tmap/files/files/Exploratory%20Testing%20Charter%20Template%20v1.2_0.pdf) 44 | 45 | ### Time Box 46 | 47 | Exploratory testers are time-boxed to test scenarios outlined in test charters. Time interval is uninterrupted and usually lasts for 90 minutes. 48 | 49 | ### Review Result 50 | 51 | Deviations identified during testing should be handled by teams according to their agreed process. 52 | 53 | ### Debrief 54 | 55 | The output result from the test should be complied and assessed if the actual results are the same as expected in charters. A decision should be made if further testing should be carried out. 56 | 57 | ## Exploratory testing vs Ad-hoc testing 58 | 59 | Ad-hoc testing usually are unscripted and unplanned while Exploratory Testing is a thoughtful method, where tester finds test scenarios prior to the testing and records their test execution findings. 60 | 61 | ## Conclusion 62 | 63 | Exploratory testing overcomes the limitation of scripted testing. It offers quick test feedback of the application/system and helps improving test case suite. Constant learning and adaptability are its main ethos. 64 | 65 | **Please Note:** 66 | 67 | A team COULD use exploratory testing, but it **_MUST NOT_** replace automated testing. As a prerequisite for Exploratory testing, team SHOULD prepare and review test charters. Any Defects/Deviations found MUST be handled according to the team's standard practices. 68 | 69 | ## References 70 | 71 | Testing, E. (n.d.). Retrieved from https://en.wikipedia.org/wiki/Exploratory\_testing 72 | -------------------------------------------------------------------------------- /quality-assurance/http-api-mocking-tools.md: -------------------------------------------------------------------------------- 1 | # Mocking HTTP Endpoints 2 | 3 | This section covers tool(s) to be used for creating mock HTTP endpoints/APIs for use as test doubles in the absence of real services. 4 | 5 | ## Order of preference 6 | 7 | We should mock services in the following order of preference: 8 | 9 | 1. WireMock instantiated in code 10 | 1. Deployed WireMock instances 11 | 1. Bespoke deployed mock services 12 | 13 | In general, code for mocks should live in the same repository as the tests which use them, not with the service that is being mocked. 14 | 15 | ## WireMock 16 | 17 | ### Uses 18 | 19 | Many simple HTTP endpoint mocking problems are solved using WireMock. Parsing requests for string values, serving templated responses, simulating errors and making subsequent calls to other URIs are all built-in features. 20 | 21 | WireMock stubs can run standalone and be deployed as continuously running services (e.g. to azure as a container instance/app or web app). 22 | 23 | >When using containers refer to the [container policy](/software-engineering-policies/Containers/ContainerPolicy.md). 24 | 25 | 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). 26 | >**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.** 27 | 28 | ### Examples 29 | 30 | The simplest way to use WireMock in tests directly in your test project is to pull in the library [WireMock.Net](https://www.nuget.org/packages/WireMock.Net) and then use a `WireMockServer` object like `server` below 31 | 32 | ``` 33 | 34 | var server = WireMockServer.Start(); 35 | server.Given(Request.Create().WithPath("/mock").UsingGet()) 36 | .RespondWith(Response.Create() 37 | .WithStatusCode(200) 38 | .WithBody("Hello world!") 39 | ); 40 | 41 | ``` 42 | 43 | This will create an http mock service that responds to requests as defined. You can use `server.Urls` to find the endpoint url if needed. 44 | 45 | For an example of using WireMock as a standalone app that can be deployed, such as for deployed system level testing, see [this example template](https://github.com/UKHO/TemplateForWiremock). 46 | 47 | See the [WireMock.net wiki](https://github.com/WireMock-Net/WireMock.Net/wiki) for the complete guide to usage. 48 | 49 | ## Bespoke API mocks 50 | 51 | Use WireMock wherever possible for creating HTTP API mocks _unless_ your requirements: 52 | 53 | - Are beyond fixed or templated HTTP responses and callbacks (including to other URIs) and basic unhappy path tests, most of which WireMock can cover. 54 | - Would make a WireMock based solution more effort or complexity than creating a bespoke mock. 55 | 56 | 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). 57 | -------------------------------------------------------------------------------- /quality-assurance/images/bdd_tree_swing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/bdd_tree_swing.png -------------------------------------------------------------------------------- /quality-assurance/images/dicovery_formulation_automation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/dicovery_formulation_automation.png -------------------------------------------------------------------------------- /quality-assurance/images/example_mapping.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/example_mapping.png -------------------------------------------------------------------------------- /quality-assurance/images/test-pyramid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/test-pyramid.png -------------------------------------------------------------------------------- /quality-assurance/images/the_test_pyramid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/the_test_pyramid.png -------------------------------------------------------------------------------- /quality-assurance/images/the_test_pyramid_updated.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/the_test_pyramid_updated.png -------------------------------------------------------------------------------- /quality-assurance/images/zap2.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap2.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap3.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap3.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap4.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap4.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap5.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap5.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap6.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap6.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap7.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap7.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zap8.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zap8.jpg -------------------------------------------------------------------------------- /quality-assurance/images/zapazuresetup.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/quality-assurance/images/zapazuresetup.jpg -------------------------------------------------------------------------------- /quality-assurance/manual-test-scripts.md: -------------------------------------------------------------------------------- 1 | # Manual Test Scripts 2 | 3 | This section describes recommended practices when creating manual test scripts at the UKHO. 4 | 5 | ## Tools 6 | 7 | It is recommended that Azure DevOps Test Plans are used to record scripts. This has the following benefits: 8 | 9 | - Integration with the rest of DevOps: e.g. linking to PBIs, bug tracking, iteration planning etc. 10 | - A test execution environment together with recording tools. 11 | - Shared steps, parameterised tests. 12 | - The advantages of a cloud-based tool in terms of cost, availability etc. 13 | 14 | In some circumstances it may not be practical to use Azure Devops, typically: 15 | 16 | - If there are a large number of test scripts already in existance in some other format (e.g. spreadsheets). 17 | - If the testers are not licensed in the use of Azure Devops, for example during UAT. 18 | 19 | In these cases, it is acceptable to use MS Office applications to document tests. Please see the [guidance on user acceptance testing for a suitable template](./user-acceptance-testing.md) 20 | 21 | ## Best practices 22 | 23 | - Favour _requirement based suites_ where it is possible to link test cases to PBIs. 24 | - Otherwise, _static suites_ can be used. 25 | - It is common for test suites to be organised according to the sprint in which they are exercised. However, at the end of a project these must be re-organised according to functional area. 26 | - Shared steps **must** be used for common functionality in order to make maintenance easier. 27 | - Parameters **must** be used where the test case can be run with different data, or if inputs should be recorded. 28 | -------------------------------------------------------------------------------- /quality-assurance/performance-test-checklist.md: -------------------------------------------------------------------------------- 1 | # Performance testing checklist 2 | 3 | ## Purpose of this document 4 | 5 | This document lists activities that you should consider when planning performance testing. 6 | 7 | ## Activity list 8 | 9 | ### Establish business requirements 10 | 11 | - What are the requirements for resilience under load (e.g. availability, responsiveness)? 12 | - What will be typical and peak usage of the system? 13 | - What are the requirements for scaling? 14 | - What are typical patterns of usage (e.g. peaks, types of request)? 15 | 16 | ### Agree types of performance testing to carry out, and data to gather 17 | 18 | e.g. 19 | 20 | - [Load testing](https://artoftesting.com/types-of-performance-testing#Load_testing) 21 | - [Soak / Endurance testing](https://artoftesting.com/types-of-performance-testing#Endurance_testing) 22 | - [Stress Testing](https://artoftesting.com/types-of-performance-testing#Stress_testing) 23 | 24 | For each type of testing, work out what data must be collected to support quality judgements. For example, for load testing you might collect data about response times and failure rates and also data regarding SUT health such as CPU and memory usage. For soak testing, you will additionally want to track SUT health data in more detail, looking for upward trends in things such as memory usage, database connections, and threads. 25 | 26 | For each type of testing, work out whether it is appropriate to run it as part of delivery pipelines. 27 | 28 | ### Manage Technical Stakeholders 29 | 30 | Depending on the technical context, ensure technical stakeholders are happy with what is planned. This is particularly important if on-prem resources will be subjected to load, where members of the tech ops team will need to be consulted. 31 | 32 | ### Design system under test (SUT) 33 | 34 | Design the system that will be tested. This should be as close to the live system as possible. Where possible, it should not contain elements of infrastructure shared with production systems. 35 | 36 | ### Select tools 37 | 38 | Consult team tech radars for currently in-use technologies. 39 | Depending on the types of testing planned, you will typically be using some sort of load testing tool. The approved load testing tool is [K6](https://k6.io/). For more complex scenarios you might use other technologies, e.g. for collecting, correlating and visualising results. It is suggested that you use cloud-based Grafana for visualising k6 output, as per [this](https://k6.io/docs/results-output/real-time/cloud/). 40 | 41 | ### Design performance test tool infrastructure 42 | 43 | Design the infrastructure that the test tool will sit on, together with any other data-gathering infrastructure. 44 | 45 | ### Document in the test approach document 46 | 47 | Add the decisions made so far into the test approach document. 48 | 49 | ### Control technical risks 50 | 51 | - Identify potential technology risks, e.g. obscure authentication mechanisms. 52 | - Carry out spike work to provide information on risks. 53 | 54 | ### Design test data 55 | 56 | - The initial data state of the system should be realistic while being subject to performance testing. 57 | - Design these baseline data, create scripts / data loads / images. 58 | 59 | ### Commission SUT environment 60 | 61 | ### Control costs 62 | 63 | - Understand how the planned performance testing will affect cloud costs. 64 | - Establish what elements of the SUT and test infrastructure will automatically scale, and which are metered. 65 | - Calculate costs of the planned test 66 | - Establish monitoring / subscription limits to manage costs 67 | 68 | ### Establish observability in SUT 69 | 70 | - Where data about the SUT are required in order to make a quality judgement (e.g. CPU usage, number of internal errors), establish ways of collecting these. 71 | 72 | ### Script tests 73 | 74 | - Use sensible software engineering practices (e.g. code review, source control) 75 | 76 | ### Run tests 77 | 78 | - Collect and evaluate data 79 | - Iterate 80 | 81 | ### Add performance tests to CI 82 | 83 | ### Include results in TSR 84 | 85 | ### Completion 86 | 87 | Ensure load test artefacts are stored for future use according to team policy (typically in source control). Include all code and deployment scripts. 88 | 89 | Performance test results are often used as benchmarks for future testing. It is therefore important to store results in a known repository (e.g. Devops wiki), where it must be clear which version of the software, environment etc. produced which set of results. 90 | -------------------------------------------------------------------------------- /quality-assurance/safety-assurance-guidance.md: -------------------------------------------------------------------------------- 1 | # Safety assurance guidance 2 | 3 | This policy describes the Software Engineering Team’s policy and process for ensuring our SOLAS products are created and changed with appropriate consideration given to safety. 4 | 5 | ## Goals 6 | 7 | - Minimise the causes of product delay and inaccuracy introduced through the software we create. 8 | - Provide traceability for the delivery of safety requirements 9 | - Create full delivery team awareness of the safety impact of the software they create 10 | - Prompt high-value team conversations about safety 11 | - Not burden teams with low-value bureaucracy 12 | - Provide safety-related analysis on a just-in-time basis, rather than through wasteful up-front effort 13 | 14 | ## Overview of approach 15 | 16 | Our approach is closely related to our successful Developer Threat Modelling process which is used as part of our security lifecycle. 17 | 18 | The test engineer in each delivery team is responsible for enforcing our safety practices. They run a lightweight process of tagging work items as safety-related and then creating barriers and mitigations to safety hazards. 19 | 20 | If teams need more information about the safety context of their work, they will request that it is provided by product owners. 21 | 22 | ## Identifying safety-related projects 23 | 24 | A team’s product owner is accountable for establishing whether their current delivery is safety-related. 25 | 26 | If the delivery is safety-related, then the team’s “definition of done” must contain a statement to the effect that safety modelling must have been carried out for every PBI (work item). 27 | 28 | ## Process – safety modelling 29 | 30 | When developing safety-related software, the following process must be followed: 31 | 32 | 1. If a PBI is considered as potentially relevant to safety, it must be marked in the work tracking system with the standard tag ‘Safety Pending’. 33 | 1. The development team must then discuss safety requirements for that PBI. This discussion may be at any team event (e.g. refinement, threat-modelling, or a specific safety meeting). 34 | 1. Under the direction of the test engineer, the team must discuss whether a failure condition relating to the PBI can cause an error or delay in the product. If it is decided that this is the case, the PBI must be marked with the standard tag ‘Safety’. If it is not the case, then all safety tags may be removed. 35 | 1. The team treats the potential hazard as a mini [bow tie](https://www.youtube.com/watch?v=P7Z6L7fjsi0) analysis, considering 36 | - Barriers to the failure condition happening 37 | - Mitigations to prevent the failure condition creating error or delay 38 | 1. These barriers and mitigations are expressed as acceptance criteria on the PBI. As a result their implementation, testing and move to production will be traceable in the work tracking tool. 39 | 40 | ## Accountability for safety modelling 41 | 42 | The team’s Lead Developer is accountable for this process being followed. However, note that the process can be run by anyone in team. 43 | 44 | ## Skills 45 | 46 | All participants must have a basic understanding of [bow tie](https://www.youtube.com/watch?v=P7Z6L7fjsi0) risk analysis. Training material is provided by the Test Practice (search for "safety processes for software engineering" on the corporate Learning Management System). 47 | 48 | ## Obtaining more information for the process 49 | 50 | At any point during a delivery, the development team can ask for more information about the safety context of their work, in order to effectively carry out safety modelling. Typically, this will consist of further information about wider IT or business processes, how these contribute to safety, and what mitigations already exist. The recommended format for this information is the [bow tie](https://www.youtube.com/watch?v=P7Z6L7fjsi0) diagram, but this is not mandated. The Product Owner is responsible for obtaining any such information that the team requires. 51 | 52 | For more information on Safety assurance guidance, please speak to a memeber of QA Team 53 | 54 | ## Safety Debt 55 | 56 | 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*. 57 | 58 | -------------------------------------------------------------------------------- /quality-assurance/test-code-standards.md: -------------------------------------------------------------------------------- 1 | # Test Automation Standards 2 | 3 | ## Test Code 4 | 5 | * Test Automation code should adhere to the same standard as production code 6 | * Formatting standards should reflect standard in use by development teams (e.g. Google Code Standard, Microsoft) 7 | * Standard coding principles apply (e.g. SOLID, DRY) 8 | 9 | ## Unit Testing 10 | 11 | * Aim for naming consistency. Common standard is to use a When-Then name, for example, WhenTwoItemsExistsThenBothItemsAreReturned 12 | * Follow best practice: 13 | * Tests for results not functionality 14 | * One assertion per test 15 | * Tests should be isolated, i.e. have no dependencies on other tests nor on order of execution 16 | 17 | ## API Testing 18 | 19 | * Perform full happy/unhappy path tests at this level 20 | * Interactions with APIs should be abstracted into a separate service/facade, not alongside the test code 21 | 22 | ## UI Testing 23 | 24 | * Only use for e2e tests or explicit UI features at this level 25 | * Interactions with UIs should be abstracted into a separate service/facade, not alongside the test code (e.g., Page Object Model) 26 | 27 | ## SpecFlow and Cucumber 28 | 29 | * Consider whether using these are required - 30 | * will it add value, 31 | * are they clearly defined and allow for ease in maintenance, 32 | * will a stakeholder be reading the tests, 33 | * or can the extra technical layer be avoided? 34 | * If using, then need to consider their accessibility 35 | * using (see livingdocs [https://docs.specflow.org/projects/specflow-livingdoc/en/latest/sbsguides/sbsazdo.html] with in the Azure Devopsm framework, or 36 | * publish the tests to a website for easy access using Pickles (see our [Pickles Example Project](test-repositories.md)) 37 | * If considered necessary then: 38 | * The feature name should reflect the area being tested 39 | * Is there a need for a background task, moving repeated steps into a Background that will be run before eash scenario 40 | * The type of Scenario that could be used eg Single 'Scenario' or data driven 'Scenario Outline' 41 | * The scenario name should reflect the purpose of the test, e.g. “Ensure two numbers are added correctly” rather than “add two numbers” or “add” 42 | * Similar scenarios should be in one feature file – a feature file should only contain similar scenarios 43 | * Ensure only one result is tested per scenario, try to avoid having too many assertions, better to split into different scenario 44 | * Perform technical setup and teardown in the Steps classes, not in the Gherkin. 45 | 46 | ## Test and Defect Management 47 | 48 | * For C# projects, unit, integration and UI (whether this is SpecFlow or playwright driven) tests should exist in separate projects 49 | * Open defects should be managed; a regular team/project review session is recommended 50 | -------------------------------------------------------------------------------- /quality-assurance/test-policy.md: -------------------------------------------------------------------------------- 1 | # Test Policy 2 | 3 | The purpose of this document is to communicate the policy for UKHO for testing of new and updated software, 4 | 5 | ## Our goals for testing 6 | 7 | - To ensure our safety-related systems do not cause inaccuracy or delay to our products 8 | - To ensure our software maintains the good reputation of the organisation 9 | - To support our agile processes, allowing frequent releases containing valuable changes to our users 10 | - To spend our time on the most valuable testing activities 11 | 12 | ## Scope of testing 13 | 14 | Our testing covers functional and non-functional areas as described in our [strategy](test-strategy.md). 15 | 16 | ## Who tests 17 | 18 | The Test Practice consists of a group of test engineers who provide a testing capability across the UKHO software delivery teams. It also provides oversight of the testing activities of our delivery partners. 19 | 20 | Where other members of the business carry out software testing, the Practice is available to offer help and advice. 21 | 22 | ## Who manages Testing 23 | 24 | Software Engineering Team Managers line manage all test engineers. However, test engineers are task-managed by the delivery programs in conjunction with the Head of Software Engineering. 25 | 26 | ## The Testing Life-Cycle 27 | 28 | The UKHO follows its Delivery Governance Framework (DGF), which contains references to testing governance activities. In summary, a standard Test Approach document must be written at the start of developing the Beta product, and a Test Summary Report must be created and signed off by stakeholders before the Beta is released. 29 | 30 | ## Testing Processes 31 | 32 | Test processes may differ by team or project, according to individual circumstances. All test approaches must conform to the UKHO's [test strategy](test-strategy.md). 33 | 34 | ## Test data 35 | 36 | It is the UKHO Policy that live data should not be used for testing. Where a copy of live data is used then its use is to be risk assessed and the data sanitised as appropriate, removing references to customers, employees and UKHO corporate proprietary information. 37 | -------------------------------------------------------------------------------- /quality-assurance/test-repositories.md: -------------------------------------------------------------------------------- 1 | # GitHub Repositories 2 | 3 | This page lists the UKHO test-related repositories on GitHub. 4 | 5 | ## Demo API Test Framework 6 | 7 | Example Java project for API testing, using REST-assured and obtaining secrets from an Azure Key Vault. 8 | 9 | 10 | 11 | ## OWASP ZAP Scan 12 | 13 | Provides the ability to execute a Full Scan against a web application using the OWASP ZAP Docker image within an Azure DevOps pipeline. 14 | 15 | 16 | 17 | ## Playwright Template 18 | 19 | Demonstrates the Page Object Model pattern using Playwright and TypeScript. 20 | 21 | 22 | 23 | 24 | ## K6 Reporting 25 | 26 | Documentation and scripts for how to set up K6 reporting infrastructure (using InfluxDB and Grafana) 27 | 28 | 29 | 30 | 31 | ## WinAppDriver 32 | 33 | Example C# project to demonstrate how to use WinAppDriver to drive a WPF application and run UI tests in a Azure Devops pipeline. 34 | 35 | 36 | -------------------------------------------------------------------------------- /quality-assurance/ukho-quality-charter.md: -------------------------------------------------------------------------------- 1 | # UKHO Delivery Quality Charter 2 | 3 | This is the UKHO Delivery Quality Charter - a set of objectives that will improve how teams can quality assure their software. 4 | 5 | ## The Team 6 | 7 | * All members of the team are equal – there should be no differences between developers and testers in: 8 | * Permissions they have been assigned (e.g. permissions to access environments). 9 | * Access to hardware or software. 10 | * Weight of opinion. 11 | * Teams that are multi-disciplinary, cross-functional and equal achieve better results. 12 | 13 | ## Ways of Working 14 | 15 | * Planning, creating and executing tests (including manual testing) is the responsibility of **everyone** in the team. 16 | * The role of the tester in the team is to **champion** quality assurance and testing at **all** stages of the development process. 17 | * The tester ensures that a test approach is created and agreed with an appropriate set of stakeholders. The whole delivery team is responsible for the quality of the test approach, and for carrying it out. 18 | * The tester ensures that information about testing is gathered into a Test Summary Report (TSR), and that it is reviewed by an appropriate set of stakeholders. The tester must ensure that all members of the team that have contributed to development understand the testing and agree with the conclusion of the TSR. 19 | * Test approaches should reflect the [UKHO Test Strategy](test-strategy.md), with appropriate levels of automated, manual and non-functional testing. 20 | 21 | 22 | ## Acceptance Criteria 23 | 24 | * Every story will have acceptance criteria added before being worked on. 25 | * Acceptance criteria will not be changed without cross-team awareness. 26 | * Acceptance criteria will be testable, i.e. capable of being proven true or false. 27 | * Testers should champion the use of good quality acceptance criteria. 28 | 29 | For more details see our '[Acceptance Criteria](acceptance-criteria.md)' page. 30 | 31 | 32 | 33 | -------------------------------------------------------------------------------- /quality-assurance/user-acceptance-testing.md: -------------------------------------------------------------------------------- 1 | ## What is User Acceptance Testing 2 | 3 | UAT means testing software against its business requirements i.e. does it solve the business problem as intended? UAT should cover key business rules and logic, and all the important user journeys that are important for the businees 4 | 5 | ## Who carries out UAT 6 | 7 | Business users are best placed to do UAT, as they are aware of the reality of their business, business processes, roles etc. Sometimes, a tester will act in place of users. 8 | 9 | ## When does UAT happen 10 | 11 | It will typically take place once a functioning system has been delivered, often after system testing. Note that UAT needs to have the normal rigour applied with regards to specifying environments and software versions, so that any faults can be properly attributed and reproduced. 12 | 13 | ## Is UAT always necessary 14 | 15 | No. If a project been delivered with an agile process, each increment of the software should have shown to its users during development. In this case UAT might not be necessary. 16 | 17 | UAT is most likely to be required when software has been delivered by external partner following a waterfall process. Note that in these cases, the UAT phase needs to be included in the Statement of Requirements we send to the supplier, detailing the partner's involvement, entry and exit criteria, etc. 18 | 19 | # What needs to be tested 20 | 21 | The best way of identifying tests is to survey users about the business processes they carry out. Alternatively, business requirements documents can be used. 22 | 23 | # Does UAT need to be scripted 24 | 25 | UAT must be scripted, but this should ideally be at a high level, in only enough detail to make the intended outcomes clear. The aim should be for users to use the software as they would normally do (i.e. to try and carry out business tasks, using any manuals etc. if necessary), rather than following step-by-step instructions. 26 | 27 | # What tools should be used 28 | 29 | Although use of Azure Devops is recommended, it is common for this to *not* be used. This is due to lack of licenses and skills for the participants. MS Excel, or any suitable software that the users are comfortable with may be used to store scripts and record issues. The following UAT template can be used to document requirements, test cases and bugs found during UAT testing. Bugs then need to be translated into the development team's work tracking software (if there is development work required. If the project consists of product(s) purchased from 3rd party suppliers, then the bugs need to be raised as defects with the suppliers). When using other tools, care should be taken to version control them. 30 | 31 | [UAT Test Template.xlsx](https://github.com/UKHO/docs/files/13500038/UAT.Test.Template.xlsx) 32 | 33 | # The role of the tester in UAT 34 | 35 | The UKHO tester does the following: 36 | 37 | - Ensures the goals and practices of UAT are clear to all stakeholders 38 | - Establishes tooling and ways of working 39 | - Works with users, business analysts and other stakeholders to identify and document tests 40 | - Ensures that the planned UAT has sufficient coverage to verify the software, possibly mapping documented business requirements back to tests 41 | - Works with users to plan the work 42 | - Works with users to plan and create test data 43 | - Coaches users in testing techniques, including ways to document faults. 44 | 45 | -------------------------------------------------------------------------------- /quality-assurance/web-accessibility-testing.md: -------------------------------------------------------------------------------- 1 | # How to test a web service for Accessibility 2 | 3 | ## Overview 4 | 5 | When testing for accessibility you will need to include the following in your approach: 6 | 7 | * Automated testing to identify common problems 8 | * Manual testing using browser plugins that will automatically report problems 9 | * Manual testing using a keyboard only 10 | * Manual testing using screen readers 11 | * Manual testing using screen magnifiers 12 | * Manual testing using voice control 13 | 14 | You also need to consider cross-browser testing. Unless you are supporting a single browser it's unlikely you will have enough time to complete all testing against all browsers. Therefore your test approach should be to carry out a selection of the above against all supported browsers. 15 | 16 | ## Test Approach 17 | 18 | 1. Automated testing using a tool in your build pipeline to identify common problems. 19 | 1. Manual testing using browser plugins against each page of your website. Note the different browsers supported by each. 20 | 1. Manual testing using assistive technologies (i.e. screen readers, screen magnifiers and voice control). 21 | 22 | Set testing tools to WCAG 2.1 AA standard 23 | 24 | ## Automated Testing 25 | 26 | * [axe-core](https://github.com/dequelabs/axe-core) 27 | * [cypress-axe](https://github.com/component-driven/cypress-axe) 28 | * [axe-playwright](https://www.npmjs.com/package/axe-playwright) - axe-core integrated with Playwright test framework. 29 | 30 | ## Manual Testing 31 | 32 | ### Browser plugins 33 | 34 | * [Microsoft Accessibility Insights](https://accessibilityinsights.io/docs/en/web/overview/) - for Edge and Chrome 35 | * [WAVE](https://wave.webaim.org/extension/) - for Chrome and Firefox 36 | * [a11yTools](https://apps.apple.com/us/app/a11ytools-web-accessibility/id1364813335?mt=12) - Safari on MacOS 37 | 38 | ### Keyboard only 39 | 40 | Use the app using the keyboard only. See [WebAim Keyboard Accessibility](https://webaim.org/techniques/keyboard/) to understand what to look for. 41 | 42 | ### Assistive Technologies 43 | 44 | Read these guides to get an overview on how to test with assistive technologies: 45 | 46 | * [gov.uk - testing with assistive technologies](https://www.gov.uk/service-manual/technology/testing-with-assistive-technologies). 47 | * [BBC - how to use the individual assistive technologies](https://bbc.github.io/accessibility-news-and-you/assistive-technology/testing.html). 48 | 49 | #### Screen readers 50 | 51 | * [NVDA](https://www.nvaccess.org/download/) - Windows 52 | * [Windows Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1) - built into Windows 10 but not used by many people so only use if NVDA cannot be 53 | * [Apple VoiceOver](https://www.apple.com/voiceover/info/guide/_1121.html) - MacOS 54 | 55 | Note that [JAWS](https://www.freedomscientific.com/products/software/jaws/) is a common screen reader but it is not free. It also attempts to fix issues on-the-fly that does not help you find issues. 56 | 57 | #### Screen magnifiers 58 | 59 | * [Windows Magnifier](https://support.microsoft.com/en-us/windows/use-magnifier-to-make-things-on-the-screen-easier-to-see-414948ba-8b1c-d3bd-8615-0e5e32204198) - Windows 10 60 | * [Apple Zoom](https://support.apple.com/en-gb/HT210978) - MacOS 61 | 62 | Note that [ZoomText](https://www.zoomtext.com/) is a recommended tool for screen magnifiers but is not free. 63 | 64 | #### Voice control 65 | 66 | * [Windows Speech Recognition](https://support.microsoft.com/en-us/windows/use-voice-recognition-in-windows-10-83ff75bd-63eb-0b6c-18d4-6fae94050571) - Windows 10 67 | * [Apple Dictation](https://support.apple.com/en-gb/HT210539) - MacOS 68 | -------------------------------------------------------------------------------- /security/ManagingSecurityConcerns/CvssScoringMetrics.md: -------------------------------------------------------------------------------- 1 | # CVSS Scoring Metrics 2 | 3 | - [CVSS Scoring Metrics](#cvss-scoring-metrics) 4 | - [Exploitability Metrics](#exploitability-metrics) 5 | - [Attack Vector (AV)](#attack-vector-av) 6 | - [Attack Complexity (AC)](#attack-complexity-ac) 7 | - [Privileges Required (PR)](#privileges-required-pr) 8 | - [User Interaction (UI)](#user-interaction-ui) 9 | - [Scope (S)](#scope-s) 10 | - [Impact Metrics](#impact-metrics) 11 | - [Confidentiality (C)](#confidentiality-c) 12 | - [Integrity (I)](#integrity-i) 13 | - [Availability (A)](#availability-a) 14 | 15 | ## Exploitability Metrics 16 | 17 | The five Exploitability Metrics capture how the vulnerability is accessed and whether or not extra conditions are required to exploit it. 18 | 19 | ### Attack Vector (AV) 20 | 21 | This metric reflects the context by which vulnerability exploitation is possible. This metric value (and consequently the Base Score) will be larger the more remote (logically, and physically) an attacker can be in order to exploit the vulnerable component. The assumption is that the number of potential attackers for a vulnerability that could be exploited from across a network is larger than the number of potential attackers that could exploit a vulnerability requiring physical access to a device, and therefore warrants a greater 22 | 23 | ### Attack Complexity (AC) 24 | 25 | This metric describes the conditions beyond the attacker’s control that must exist in order to exploit the vulnerability. As described below, such conditions may require the collection of more information about the target, or computational exceptions. Importantly, the assessment of this metric excludes any requirements for user interaction in order to exploit the vulnerability (such conditions are captured in the User Interaction metric). If a specific configuration is required for an attack to succeed, the Base metrics should be scored assuming the vulnerable component is in that configuration. The Base Score is greatest for the least complex attacks. 26 | 27 | ### Privileges Required (PR) 28 | 29 | This metric describes the level of privileges an attacker must possess *before* successfully exploiting the vulnerability. The Base Score is greatest if no privileges are required. 30 | 31 | ### User Interaction (UI) 32 | 33 | This metric captures the requirement for a human user, other than the attacker, to participate in the successful compromise of the vulnerable component. This metric determines whether the vulnerability can be exploited solely at the will of the attacker, or whether a separate user (or user-initiated process) must participate in some manner. The Base Score is greatest when no user interaction is required. 34 | 35 | ### Scope (S) 36 | 37 | The Scope metric captures whether a vulnerability in one vulnerable component impacts resources in components beyond its *security scope*. 38 | 39 | Formally, a *security authority* is a mechanism (e.g., an application, an operating system, firmware, a sandbox environment) that defines and enforces access control in terms of how certain subjects/actors (e.g., human users, processes) can access certain restricted objects/resources (e.g., files, CPU, memory) in a controlled manner. All the subjects and objects under the jurisdiction of a single *security authority* are considered to be under one *security scope*. If a vulnerability in a vulnerable component can affect a component which is in a different *security scope* than the vulnerable component, a Scope change occurs. Intuitively, whenever the impact of a vulnerability breaches a security/trust boundary and impacts components outside the security scope in which vulnerable component resides, a Scope change occurs. 40 | 41 | The security scope of a component encompasses other components that provide functionality solely to that component, even if these other components have their own security authority. For example, a database used solely by one application is considered part of that application’s security scope even if the database has its own security authority, e.g., a mechanism controlling access to database records based on database users and associated database privileges. 42 | 43 | The Base Score is greatest when a scope change occurs. 44 | 45 | ## Impact Metrics 46 | 47 | ### Confidentiality (C) 48 | 49 | This metric measures the impact to the confidentiality of the information resources managed by a software component due to a successfully exploited vulnerability. Confidentiality refers to limiting information access and disclosure to only authorized users, as well as preventing access by, or disclosure to, unauthorized ones. The Base Score is greatest when the loss to the impacted component is highest. 50 | 51 | ### Integrity (I) 52 | 53 | This metric measures the impact to integrity of a successfully exploited vulnerability. Integrity refers to the trustworthiness and veracity of information. The Base Score is greatest when the consequence to the impacted component is highest. 54 | 55 | ### Availability (A) 56 | 57 | This metric measures the impact to the availability of the impacted component resulting from a successfully exploited vulnerability. While the Confidentiality and Integrity impact metrics apply to the loss of confidentiality or integrity of *data* (e.g., information, files) used by the impacted component, this metric refers to the loss of availability of the impacted component itself, such as a networked service (e.g., web, database, email). Since availability refers to the accessibility of information resources, attacks that consume network bandwidth, processor cycles, or disk space all impact the availability of an impacted component. The Base Score is greatest when the consequence to the impacted component is highest. 58 | 59 | More information on the CVSS score metrics can be found on the specification document [here](https://www.first.org/cvss/v3.1/specification-document). 60 | -------------------------------------------------------------------------------- /security/SecurityChampions/SecurityChampionResponsibilities.md: -------------------------------------------------------------------------------- 1 | # Security Champion Responsibilities 2 | 3 | - [Security Champion Responsibilities](#security-champion-responsibilities) 4 | - [What I do](#what-i-do) 5 | - [What I don’t do](#what-i-dont-do) 6 | - [My skills](#my-skills) 7 | - [My connections](#my-connections) 8 | 9 | ## What I do 10 | 11 | *I am a software engineer whose main job is to write code. I additionally have a responsibility to help the team write secure software, as a source of expertise and a coach.* 12 | 13 | I coach the team into creating security processes that make our systems secure while minimising the effect on development velocity. I ensure that these processes run effectively, but I don’t make myself a bottleneck or a single point of failure in the process. 14 | 15 | I ensure the team create an effective set of standards for securely developing their software. 16 | 17 | I help the team define a set of security training materials, and I make sure they are all consumed. 18 | 19 | I have expertise in pen testing tools and use them during development to harden our software. 20 | 21 | I help the team run threat modelling sessions. 22 | 23 | I help the team identify security requirements for our software. 24 | 25 | I work with the other Security Champions to: 26 | 27 | - Share best practice across teams 28 | - Create shared standards and resources 29 | - Run activities and events 30 | 31 | ## What I don’t do 32 | 33 | *I am concerned only with helping engineers to write create secure systems. There are therefore lots of security-related activities I don’t do.* 34 | 35 | I’m not an IT Security Officer. 36 | 37 | I’m not a penetration tester. 38 | 39 | I'm not responsible for keeping platforms (e.g. operating systems) patched. 40 | 41 | I don’t run Information Assurance processes, risk assessments or audits. 42 | 43 | I don’t run security investigations, security incidents or forensic investigations. 44 | 45 | I'm not the only person who cares about security. An important part of my job is to ensure all engineers make security a priority. 46 | 47 | I’m not the only person to run security activities – I coach others to run them effectively. 48 | 49 | ## My skills 50 | 51 | *I have the skills of a senior software engineer, but with additional security knowledge.* 52 | 53 | I have a broad knowledge of security risks and how to counter them. 54 | 55 | I'm an expert in how my team’s technologies must be used to keep them secure. 56 | 57 | I'm well trained and hold security-related qualifications. 58 | 59 | I'm an expert in my team’s security tooling (e.g. static analysis tools, third-party checkers). 60 | 61 | I understand the security aspects of solution architecture. 62 | 63 | I have coaching and influencing skills. 64 | 65 | ## My connections 66 | 67 | *I make connections across the organisation and the wider security community.* 68 | 69 | I use every opportunity to share my security knowledge with my team and the practice, using a variety of formats such as coaching, presentations and blogging. 70 | 71 | I seek sources of security expertise outside the UKHO, bringing in ideas and innovation. In particular, I connect with people in other parts of government. 72 | 73 | I'm an active member of the UKHO security champions group. 74 | 75 | I connect with the UKHO’s Security Team, to better understand their processes and requirements. 76 | 77 | I work closely with solution architects to understand their security goals and concerns. 78 | -------------------------------------------------------------------------------- /software-engineering-policies/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Software Engineering Policies 2 | 3 | Thank you for considering to contributing to these policies 4 | 5 | ## Contribution Processes 6 | 7 | ### Questions, Queries and Concerns 8 | 9 | Please open an issue in all situations and if necessary please `@` the policy owner and editor. 10 | 11 | ### Minor Changes (typos etc.) 12 | 13 | Please make the change on a separate branch and submit a merge request. 14 | 15 | ### Major Changes (Updating/Creating policies) 16 | 17 | - Open an issue containing detailed information on the change you would like to make 18 | - If you want to change and existing policy, please `@` the policy owner and editor 19 | - Add the `proposal` label to the issue. 20 | - With other participants and stakeholders come to a consensus whether to accept the proposal 21 | - If accepted **remove the `proposal` label and replace with `accepted`.** This should only be done with agreement from the owner (if relevant) 22 | - Make the accepted changes on a separate branch, push to GitLab and open a merge request for review 23 | - Once the changes have been reviewed, make all requested changes. This can take several rounds of `changes` -> `review` 24 | - Once the review is complete and all requested changes have been made, merge in the accepted branch 25 | 26 | > If your proposal is rejected, please close the issue and feel free to resubmit in a new issue making the necessary changes. 27 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/CloudFirst.md: -------------------------------------------------------------------------------- 1 | # Cloud First Approach 2 | 3 | [Back to main Readme](README.md) 4 | 5 | The Cloud First Approach is a strategic initiative aimed at prioritizing the adoption of cloud computing technologies in software engineering endeavors within the UK Hydrographic Office. This approach stems from the recognition of the transformative potential of cloud computing to enhance agility, innovation, and cost-effectiveness in delivering digital services. 6 | 7 | ## Guiding Principles 8 | 9 | * Agility: Embrace cloud technologies to rapidly respond to changing business requirements and market dynamics. 10 | * Security: Ensure the confidentiality, integrity, and availability of data and applications through robust security measures. 11 | * Compliance: Adhere to relevant regulatory requirements and industry standards governing data privacy, security, and governance. 12 | * Cost Optimization: Optimize cloud resources usage to maximize cost-effectiveness and operational efficiency. 13 | * Innovation: Foster a culture of experimentation and innovation by leveraging cloud-native services and capabilities. 14 | * Reliability: Ensures that workloads meet uptime and recovery targets by building redundancy and resiliency at scale. 15 | 16 | In general, security concerns are expected to take precedence over other concerns. 17 | 18 | ## Benefits and Challenges 19 | 20 | A Cloud First Approach offers numerous benefits, including: 21 | 22 | * Enhanced scalability and flexibility 23 | * Faster time to market for software solutions 24 | * Improved collaboration and productivity 25 | * Cost savings through pay-as-you-go pricing models 26 | 27 | It also presents challenges such as: 28 | 29 | * Security and compliance concerns 30 | * Operational complexity during migration and integration 31 | * Potential vendor lock-in risks 32 | 33 | [Back to main Readme](README.md) 34 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/Containers.md: -------------------------------------------------------------------------------- 1 | # Recommendations for Container Hosting / Orchestration (Rich Shawley) 2 | 3 | [Back to main Readme](README.md) 4 | 5 | ## See Container Policy 6 | 7 | ## Never Run As Root 8 | 9 | [Back to main Readme](README.md) 10 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/DataUse.md: -------------------------------------------------------------------------------- 1 | # Data Use in the cloud (Dee) 2 | 3 | [Back to main Readme](README.md) 4 | 5 | ## Statement on personal / sensitive data 6 | 7 | Personal Identifiable Information (PII) should only be held in accordance with the Data Protection Act 2018. 8 | 9 | PII should be minimised and/or anonymised in system logging. Where PII is required in logs, the PII should be pseudonymised. 10 | 11 | ![Image shows pseudonymisation allows decryption to the original PII and anonymisation is irreversible PII manipulation](images/Difference-between-anonymization-and-pseudonymization.png) 12 | 13 | ## Data Protection Act and useful respources (Links) 14 | 15 | * [An overview of the Data Protection Act 2018](https://ico.org.uk/media/for-organisations/documents/2614158/ico-introduction-to-the-data-protection-bill.pdf) 16 | * [A guide to the data protection principles](https://ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources/data-protection-principles/a-guide-to-the-data-protection-principles/) 17 | 18 | ## Georedundancy 19 | 20 | Where possible, data should be georedundant. Some cloud services have this available out-of-the-box, such as Azure Storage Accounts, and others require setting up multiple resources and designating a primary and secondary. 21 | 22 | ## Data Sovereignty (UK datacentres only) 23 | 24 | :thinking: 25 | 26 | ## Recommended / supported database solutions 27 | 28 | WIP 29 | 30 | * Support encypt at rest and transit 31 | 32 | [Back to main Readme](README.md) 33 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/Deployment.md: -------------------------------------------------------------------------------- 1 | # Deployment 2 | 3 | [Back to main Readme](README.md) 4 | 5 | ## Code Scanning 6 | 7 | Before any code is pushed into an environment it should undergo our SAST checks from [Snyk](https://app.snyk.io/login) to try and ensure that the code we are creating is not going to leave us vulnerable. Any issues found that are high or above should be dealt with before doing any deployments to an environment. Where you feel there may be an exception to this, you can reach out to our [ITSO team](mailto:ukho-itso@ukho.gov.uk) or your Lead Developers for advice on mitigation/suppression of these issues. 8 | 9 | ## Container Scanning 10 | 11 | Container images being produced for deployment into an environment should be scanned by a preferred scanning solution to ensure that we are not deploying vulnerable software. Details on our container policies can be found in the [Containers area.](/software-engineering-policies/Containers/) 12 | 13 | ## Dependency Checking for Cloud Applications 14 | 15 | It is important that we do not allow our dependencies to be the weak link in our security chain. Pipelines should use the preferred Software Composition Analysis (SCA) scanning tool that prevents any dependencies with high or above vulnerabilities to be released. Where you feel there may be an exception to this, you can reach out to our [ITSO team](mailto:ukho-itso@ukho.gov.uk) or your Lead Developers for advice on mitigation/suppression of these issues. 16 | 17 | [Back to main Readme](README.md) 18 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/DisasterRecoveryBusinessContinuity.md: -------------------------------------------------------------------------------- 1 | # Disaster Recovery & Business Continuity 2 | 3 | [Back to main Readme](README.md) 4 | 5 | A business is as only as robust as its systems and services. Ensure you have a plan to restore your services in the event of a partial or complete failure. Don't wait for a crisis to occur. Instead, prepare ahead by planning and designing your services to be robust, and ensure you have structures in place to restore your services in the event of a failure. Recommended steps include: 6 | 7 | * Know your business requirements and SLAs (Service Level Agreements). These will inform the approach taken to recovering after services fail. 8 | * Understand the risks within your services, and their potential impacts. Consider and document options to mitigate those risks. 9 | * Ensure you have systems in place for detecting outages, updating stakeholders and restoring services so you can 10 | * resolve outages quickly and efficiently, 11 | * recover from data loss or corruption 12 | * resume normal services 13 | * as fast as possible. 14 | * within the requirements of your SLAs 15 | 16 | Training is available in Business Continuity planning. This should be completed by all members of the development team: See [link](https://learning.ukho.gov.uk/course/view.php?id=18) 17 | 18 | ## Building Robust Systems 19 | 20 | * Where possible, use infrastructure as code tools, particularly Terraform (see Infrastructure as Code) 21 | * Document infrastructure requirements, especially any secrets or manual steps that cannot or should not be recorded as infrastructure as code 22 | * Consider using scaling, redundancy and load balancing solutions (such as those offered by Kubernetes) to mitigate the effects of single-service outages. 23 | * Ensure that you have scheduled backups in place for all your data, supporting metadata and auditing solutions, and that these backups are sufficient to meet the terms of your SLAs 24 | * Scheduled backups should consider using GeoRedundant or Zone Redundant storage where possible (see Georedundancy above): this ensures that services can recover in the event of data loss affecting a single data centre 25 | * Data Sovereignty implications (See Data Sovereignty above) may mean that redundancy must be limited to the UK South and UK West data centres 26 | * Set appropriate retention policies for historic data to ensure that that you can recover from partial or complete data corruption 27 | * Ensure that backup and restore processes are thoroughly and unambiguously documented 28 | * Agree and enforce secure policies for managing secrets within the team 29 | * Consider using blue / green deployments, additional environments and other solutions to ensure redundancy and consistency between your services 30 | * Consider employing external auditors to review your plans and recommend valuable improvements 31 | * Perform regular testing and auditing to ensure the integrity of your data 32 | 33 | ## Disaster Recovery 34 | 35 | * Complete and document a Disaster Recovery plan detailing how: 36 | * systems can be fully rebuilt from the ground up 37 | * following 38 | * a complete failure 39 | * a database service outage 40 | * a data corruption event 41 | * using 42 | * backups 43 | * infrastructure as code 44 | * documented manual steps 45 | * Ensure data and associated metadata can be recovered and restored from your regular backups 46 | * without data loss outside of agreed limits (usually a 2-hour time window) 47 | * within the timeframes allowed by your SLAs 48 | * without leaving data and supporting metadata out of sync 49 | * Perform a disaster recovery exercise as early as possible to ensure that your processes work as intended 50 | * Consider scheduling regular Disaster Recovery exercises: 51 | * to ensure necessary skills are maintained within the team 52 | * to ensure that documentation remains valid and up-to-date 53 | * and to maintain confidence in your recovery plan 54 | * Consider using Azure Chaos studio to test common DR scenarios 55 | 56 | [Back to main Readme](README.md) 57 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/General.md: -------------------------------------------------------------------------------- 1 | # Requirements and Recommendations for 2 | 3 | [Back to main Readme](README.md) 4 | 5 | ## Auditing 6 | 7 | ## Testing - limit scope to infra testing ?? hand off to test community ?? - RS 8 | 9 | ## Virus Scanning 10 | 11 | ## Code Analysis 12 | 13 | ## Dependency Checking for Cloud Applications 14 | 15 | ## Infrastructure as Code - Terraform, etc 16 | 17 | Terraform is UKHO's primary tool of choise for IaC and should be used for in all cases. Terraform provided multi-cloud provisioning and so is capable of deploying to any cloud provider. 18 | 19 | ### Setting up a new project 20 | 21 | The Terraform deployment template found here: https://github.com/UKHO/Terraform-Deployment-Template should be used to ensure consistency when starting up any new project. Contact the DDC team if you have any questions. 22 | 23 | ### Networking 24 | 25 | The DDC team are responsible for the creating and maintaining the networking spoke Terraform for each project. This is managed in a separate GitHub repository to the project terraform and can be found here: https://github.com/UKHO/Azure-Spokes 26 | 27 | ### Modules 28 | 29 | The DDC team manages a collection of centralised Terraform modules found here: https://github.com/orgs/UKHO/teams/tfmodules/repositories 30 | These should be used whenever possible. 31 | 32 | ### IaC Scanning (Trivy) 33 | 34 | Trivy is UKHO's Chosen IaC Scanning tool. All Infrastructure pipelines should include a Trivy Scan stage before deployment that fails the build if misconfigurations or vulnerabilities are detected. 35 | A Trivy Stage is included in the previously mentioned Terraform deployment template: https://github.com/UKHO/Terraform-Deployment-Template/blob/5ca2e1c18618dad0df84ef8c08aea87a64c3b94e/azure-pipelines.yml#L37 36 | 37 | ## Secrets Management 38 | 39 | ### Centralized Secrets Management 40 | 41 | Attempt to authenticate with secret-less (managed identities) where possible. All secrets, credentials, and sensitive data used by applications must be stored in Azure Key Vault. 42 | 43 | ### Access Control 44 | 45 | Access to Key Vault must be restricted using Azure RBAC, with access granted based on the principle of least privilege. 46 | 47 | ### Network Security 48 | 49 | Enable Private Endpoints or Service Endpoints for Key Vault to restrict access to trusted networks. 50 | 51 | ### Secret Rotation and Expiration 52 | 53 | Secrets must be rotated on a regular basis, with automation for renewal and alerting in place for any approaching expiration. 54 | 55 | ### Audit and Monitoring 56 | 57 | Key Vault access logs must be enabled and monitored for suspicious activities, with alerts configured for any unauthorized attempts. 58 | 59 | ### Secure Application Integration 60 | 61 | Applications must access secrets via Managed Identities, and all hardcoded secrets must be removed from codebases. 62 | 63 | ### Compliance 64 | 65 | All Key Vault configurations and data handling processes must align with applicable UK government standards and data residency requirements. 66 | 67 | ### Exceptions 68 | 69 | Any deviation from this policy requires a documented approval from the Information Security Officer and an approved risk assessment. 70 | 71 | [Back to main Readme](README.md) 72 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/LoggingAndMonitoring.md: -------------------------------------------------------------------------------- 1 | # Logging and Monitoring for Cloud-Based Deployments 2 | 3 | [Back to main Readme](README.md) 4 | 5 | Appropriate logging, monitoring and auditing are essential to: 6 | 7 | * Maintain confidence in your systems and services 8 | * Provide early detection of outages and other issues affecting your services 9 | * identify root causes in the event of outages, data loss, security concerns or other undesirable events 10 | 11 | Logging Recommendations: 12 | 13 | * Consider using the UKHOs centralised elasticsearch capability to ensure that all logs are captured and retained 14 | * Agree on appropriate formats and logging levels to ensure logs are available and useful in maintaining your services 15 | * Consider options to control log access and ensure logs are free from unnecessary sensitive data 16 | 17 | 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. 18 | 19 | Monitoring Recommendations 20 | 21 | * Consider implementing Elastic Cloud APM to trace interactions across your services and identify performance issues or bottlenecks 22 | * Following recent budgeting and procurement activities, APM and ElasticSearch are now the UKHO standards for logging and observability 23 | * Consider using the EventHub logging Nuget package: UKHO.Logging.EventHubLogProvider 24 | * Consider using correlation Ids to link related logs and events 25 | * Consider whether dashboards can be utilised to give developers ongoing visibility of service health, usage and performance 26 | * Consider whether automated alerts can be used to notify the development team of any outage or event 27 | * Consider how to balance necessary alerts against unnecessary noise. 28 | * Integrate solar winds for business central alerting 29 | 30 | ## On-prem vs DDC-managed vs In-team ELK/EFK stacks, etc 31 | 32 | [Back to main Readme](README.md) 33 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/PilotsLicense.md: -------------------------------------------------------------------------------- 1 | # Cloud Pilot's License 2 | 3 | [Back to main Readme](README.md) 4 | 5 | The UKHO Cloud Pilot's Licence is a new mandatory training module aimed at new starters or those moving into a development role, and is necessary to gain elevated access to UKHO cloud accounts. There are five areas of study and familiarisation: 6 | 7 | * Azure Fundamentals 8 | * UKHO Resource Naming Conventions 9 | * UKHO Hub/Spoke Architecture 10 | * UKHO Privileged Identity Management 11 | * UKHO Cloud Security 12 | 13 | For further details see the [UKHO Cloud Pilot's Licence](https://ukho.sharepoint.com/sites/SoftwareDevandTest/SitePages/Cloud-Pilot's-Licence.aspx) on Nautilus. 14 | 15 | [Back to main Readme](README.md) 16 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/README.md: -------------------------------------------------------------------------------- 1 | # Cloud Development Policy 2 | 3 | ## Purpose of this policy 4 | 5 | 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. 6 | 7 | By leveraging cloud technologies, we aim to: 8 | 9 | * Enhance the security posture of our organization by implementing robust controls and encryption mechanisms. 10 | * Ensure compliance with relevant data protection laws, industry standards, and government regulations. 11 | * Manage risks associated with cloud usage through proactive identification, assessment, and mitigation strategies. 12 | * Optimize resource utilization and drive cost savings through efficient allocation and management of cloud resources. 13 | * Facilitate scalability and flexibility to meet evolving business requirements and demands. 14 | 15 | ## Scope of this policy 16 | 17 | This policy applies to all software engineering teams and individuals within the UK Hydrographic Office who are involved in the development, deployment, and maintenance of cloud-based applications and services. 18 | 19 | ## Revision History / Schedule 20 | 21 | | Version | Date of Revision | Description of Change | Author | Approval Status | 22 | | ------- | ----- | ----- | ----- | ----- | 23 | | 0.1 | 07/11/2024 | Initial Draft | Cloud Guild | | 24 | 25 | ## Policies 26 | 27 | [Cloud First Approach](CloudFirst.md) 28 | 29 | [Guidance on Security with the Hub and Spoke Model](https://github.com/UKHO/how-do-i/blob/3373f41de95525cf795df0d9c1aae7ada2dcea86/docs/subscriptions.md?plain=1) 30 | 31 | [General Requirements and Recommendations](General.md) 32 | 33 | [Containers](Containers.md) 34 | 35 | [Deployment](Deployment.md) 36 | 37 | [Data Use in the cloud](DataUse.md) 38 | 39 | [Users](Users.md) 40 | 41 | [Disaster Recovery & Business Continuity](DisasterRecoveryBusinessContinuity.md) 42 | 43 | [Logging and Monitoring](LoggingAndMonitoring.md) 44 | 45 | [Cloud Pilot's License](PilotsLicense.md) 46 | 47 | [Tagging](Tagging.md) 48 | 49 | ### Related Policies 50 | 51 | [Security Clearance](https://github.com/UKHO/docs-private/tree/main/software-engineering-policies/CloudDevelopment/Security%20Clearance) 52 | 53 | [Nautilus Account Types & Purposes](https://ukho.sharepoint.com/sites/SoftwareDevandTest/SitePages/Account-types.aspx) 54 | 55 | [Code Review Policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/CodeReview/CodeReviewPolicy.md) 56 | 57 | [Container Policy](https://github.com/UKHO/docs/blob/main/software-engineering-policies/Containers/ContainerPolicy.md) 58 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/Tagging.md: -------------------------------------------------------------------------------- 1 | # Tagging 2 | 3 | [Back to main Readme](README.md) 4 | 5 | Applied policies require the following tags on resources: 6 | 7 | * SERVICE 8 | * ENVIRONMENT 9 | * COST_CENTRE 10 | * SERVICE_OWNER 11 | * RESPONSIBLE_TEAM 12 | * CALLOUT_TEAM 13 | 14 | Possible to use terraform `ignore_changes = [tags]` in which case tags will be inherited from resource hierarchy. 15 | 16 | Should tags be deleted they will reapply with values from resource hierarchy. 17 | 18 | Tag values can be changed and retained. 19 | 20 | Tags should be kept current. 21 | 22 | [Back to main Readme](README.md) 23 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/Users.md: -------------------------------------------------------------------------------- 1 | # Users 2 | 3 | [Back to main Readme](README.md) 4 | 5 | ## User Management (Internal and External) - Rich to talk to Neena Brown about target IDAM architecture 6 | 7 | WIP 8 | 9 | * use federated accounts over local accounts in each tenant. 10 | * use access packages where appropriate 11 | * External users should have a sponsor from the internal and external domains. 12 | 13 | ## Entra ID accounts over SAS / access keys / username/password connection strings (Paul King) 14 | 15 | WIP 16 | 17 | * use RBAC over connection strings and local accounts 18 | * For SQL: Disable SA accounts and/or SQL login (use Entra ID login only) 19 | 20 | ## Auth - Are there existing policies, should there be, who should own this (paul to chat/investigate with security guild) 21 | 22 | [Back to main Readme](README.md) 23 | -------------------------------------------------------------------------------- /software-engineering-policies/CloudDevelopment/images/Difference-between-anonymization-and-pseudonymization.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/CloudDevelopment/images/Difference-between-anonymization-and-pseudonymization.png -------------------------------------------------------------------------------- /software-engineering-policies/CodeCopyright/CodeCopyrightPolicy.md: -------------------------------------------------------------------------------- 1 | # Code Copyright Policy 2 | 3 | The topic of copyright and licensing topic is owned by the [National Archives](https://www.nationalarchives.gov.uk/). 4 | 5 | All the code we create is [Crown copyright](https://www.nationalarchives.gov.uk/information-management/re-using-public-sector-information/uk-government-licensing-framework/open-government-licence/open-software-licences/). 6 | 7 | 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. 8 | 9 | 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)”). 10 | 11 | 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. 12 | -------------------------------------------------------------------------------- /software-engineering-policies/CodeGenerationTools/CodeGenerationToolsPolicy.md: -------------------------------------------------------------------------------- 1 | # Use of Code Generation Tools 2 | 3 | ## Purpose 4 | 5 | This policy establishes guidelines and responsibilities for the use of code generation tools by colleagues within the UK Hydrographic Office. Its purpose is to maximize productivity and innovation while safeguarding data security, intellectual property, legal compliance, and code quality. 6 | 7 | ## Scope 8 | 9 | This policy applies to all employees, contractors, and third-party users who utilize code generation tools, including, but not limited to, tools that offer AI-assisted code completion, generation, or modification in any development environment across the organization. 10 | 11 | ## Data Security and Confidentiality 12 | 13 | * Data Handling: Users must ensure that any adopted tools do not inadvertently share sensitive, classified, or personally identifiable information (PII) with external services during code generation. 14 | 15 | * Transmission and Storage: All interactions with adopted code generation tools should comply with the organization’s encryption and data residency policies, ensuring that any data transmitted is securely handled. 16 | 17 | * Compliance: The use of adopted tools must be aligned with all internal and external information security requirements, including those applicable to cloud-hosted environments. 18 | 19 | ## Intellectual Property and Licensing 20 | 21 | * Ownership: The UK Hydrographic Office retains ownership of the codebase. Users must understand how generated code is integrated, ensuring that no third-party intellectual property rights are inadvertently compromised. 22 | 23 | * Licensing Compatibility: All outputs produced by code generation tools should be verified for licensing compliance. Generated code must not introduce code snippets that conflict with the organization's licensing policies. To ensure compliance and mitigate risks, only vetted and appropriately licensed tooling should be used for UKHO codebases. 24 | 25 | * Review: Generated code should be treated as a draft and subject to full review before integration, ensuring alignment with the organization’s IP and licensing standards. 26 | 27 | ## Legal and Regulatory Compliance 28 | 29 | * Regulatory Alignment: Usage of code generation tools must comply with all relevant local, national, and international regulations, including data protection laws (e.g., GDPR) and government-specific compliance requirements. 30 | 31 | * Auditability: Tools and processes should be implemented to track and log the use of code generation technologies, ensuring that activities can be audited for compliance with legal and regulatory standards. 32 | 33 | ## Code Quality and Review Process 34 | 35 | * Human Oversight: Code generated by these tools must undergo the same review, testing, and quality assurance processes as manually written code. 36 | 37 | * Integration: Developers should integrate the output from code generation tools into the existing codebase only after thorough review and necessary modifications. 38 | 39 | * Continuous Improvement: Feedback on generated code should be documented to continuously improve tool usage and integration practices. 40 | 41 | ## Training and Best Practices 42 | 43 | * Training: Training programs should be provided for all relevant roles, including software engineers (junior to principal), DevOps, and Data Engineers. Training should cover the effective use of these tools and adherence to this policy. 44 | 45 | * Best Practices: Documentation and guidelines outlining best practices for using code generation tools should be maintained and updated regularly. Users should be encouraged to share feedback and lessons learned. 46 | 47 | * Ongoing Education: Updates and refresher sessions should be conducted to keep all users informed about changes in the tools, best practices, and policy updates. 48 | 49 | ## Operational Integration and Monitoring 50 | 51 | * Tool Compatibility: Adopted tools should be evaluated to ensure that they integrate effectively with the existing technology stack, workflows, and cloud environments. 52 | 53 | * Usage Monitoring: Monitoring the utilization of these tools should be available to identify any deviations or potential misuse. 54 | 55 | * Usage Restrictions: Appropriate usage limits and access controls must be available for scenarios involving particularly sensitive or critical code to mitigate associated risks. 56 | 57 | ## Risk Management 58 | 59 | * Risk Assessment: Regularly assess risks associated with the use of code generation tools, including the potential for introducing vulnerabilities or unlicensed code. 60 | 61 | * Review Cycle: The policy and associated practices should be reviewed periodically to reflect evolving technology, regulatory changes, and emerging best practices. 62 | 63 | ## Transparency and Accountability 64 | 65 | * Feedback Mechanism: A feedback loop should be established, enabling users to report problematic outputs or suggest improvements. This information will be used to refine both tool usage guidelines and the policy itself. 66 | 67 | * Responsibility: Each user is responsible for ensuring that the generated code complies with this policy and does not compromise the organization’s security or quality standards. 68 | -------------------------------------------------------------------------------- /software-engineering-policies/CodeReuse/CodeReusePolicy.md: -------------------------------------------------------------------------------- 1 | # Code Reuse Policy 2 | 3 | Code assets **must** be reused where possible. 4 | 5 | Lead Engineers are accountable for effective: 6 | 7 | - Reuse of assets from within their teams and from other teams and programmes; 8 | - Communication of available assets to other teams; 9 | 10 | ## Verification 11 | 12 | Teams should be seen to be actively using shared assets 13 | -------------------------------------------------------------------------------- /software-engineering-policies/CodeReview/CodeReviewPolicy.md: -------------------------------------------------------------------------------- 1 | # Code Review Policy 2 | 3 | ## What are code reviews 4 | 5 | Peer code reviews are a valuable and **mandatory** part of the software development process. These reviews can take various forms, for example a desk based review with another developer or a walkthrough of some significant changes with the entire team. 6 | 7 | ## What should be reviewed 8 | 9 | **All** changes which are to be committed to source control **must** be subject to a review. 10 | 11 | Code reviews must be conducted on code directly from source control. You **must not** review code deployed to shared folders or drives, or from test deployments. 12 | 13 | Each team **must** maintain a means of checking that all code is reviewed. This might consist of a report that is generated showing un-reviewed changes, or the preferred approach of a workflow within version control tooling which enforces it, e.g. via pull requests. 14 | 15 | ## What else should be checked 16 | 17 | The review should ensure that the change set(s) **must** have a link to an associated work item. 18 | 19 | All change set(s) **must** have an appropriate comment explaining the change, i.e. a good commit message. 20 | 21 | ## When must the review be completed 22 | 23 | It is strongly advised that reviews should be completed within 1-2 days of the coding task being completed. 24 | 25 | Reviews **must** be completed before the change set is merged into a different branch and prior to code entering a branch which has a deployment path to a formal testing environment such as UAT. 26 | 27 | A PBI is not completed until any code changes have been reviewed and any further changes from the review completed. The completion of code reviews **must** be included in a team's definition of done. 28 | 29 | ## Evidence of review 30 | 31 | There **must** be evidence that the code changes associated with a check-in have been reviewed. 32 | 33 | ## Verification 34 | 35 | There are two means of verification: 36 | 37 | - A workflow should be created which enforces a code review before work can enter the main codebase. 38 | - Alternatively, where the tooling does not support an enforced workflow, a report or similar must be open to inspection showing that all code reviews have been carried out. 39 | -------------------------------------------------------------------------------- /software-engineering-policies/CodingStandards/CssCodingStandards.md: -------------------------------------------------------------------------------- 1 | # CSS Coding Standards 2 | 3 | ## Validity 4 | 5 | Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code and use tools such as the [W3C CSS validator](http://jigsaw.w3.org/css-validator/) to test. 6 | 7 | ## Capitalization 8 | 9 | All code has to be lowercase: This applies to CSS selectors, properties, and property values (with the exception of strings). 10 | 11 | ```css 12 | /* Not recommended */ 13 | color: #E5E5E5; 14 | 15 | /* Recommended */ 16 | color: #e5e5e5; 17 | ``` 18 | 19 | ## Id and Class Naming 20 | 21 | The id of an element **must** unique on a page, you **should NEVER** repeat. 22 | 23 | Use meaningful or generic ID and class names. 24 | 25 | Instead of presentational or cryptic names, always use ID and class names that reflect the purpose of the element in question, or that are otherwise generic. 26 | 27 | Names that are specific and reflect the purpose of the element should be preferred as these are most understandable and the least likely to change. 28 | 29 | Generic names are simply a fallback for elements that have no particular or no meaning different from their siblings. They are typically needed as “helpers.” 30 | 31 | Using functional or generic names reduces the probability of unnecessary document or template changes. 32 | 33 | ```css 34 | /* Not recommended: meaningless */ 35 | #yee-1901 {} 36 | 37 | /* Not recommended: presentational */ 38 | .button-green {} 39 | .clear {} 40 | 41 | /* Recommended: specific */ 42 | #gallery {} 43 | #login {} 44 | .video {} 45 | 46 | /* Recommended: generic */ 47 | .aux {} 48 | .alt {} 49 | ``` 50 | 51 | ## Id and Class Name Style 52 | 53 | Use ID and class names that are as short as possible but as long as necessary. Try to convey what an ID or class is about while being as brief as possible. 54 | Using ID and class names this way contributes to acceptable levels of understandability and code efficiency. 55 | 56 | ```css 57 | /* Not recommended */ 58 | #navigation {} 59 | .atr {} 60 | 61 | /* Recommended */ 62 | #nav {} 63 | .author {} 64 | ``` 65 | 66 | ## Type Selectors 67 | 68 | Avoid qualifying ID and class names with type selectors. 69 | 70 | Unless necessary (for example with helper classes), do not use element names in conjunction with IDs or classes. 71 | 72 | Avoiding unnecessary ancestor selectors is useful for [performance reasons.](http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/) 73 | 74 | ```css 75 | /* Not recommended */ 76 | ul#example {} 77 | div.error {} 78 | /* Recommended */ 79 | #example {} 80 | .error {} 81 | ``` 82 | 83 | ## Shorthand Properties 84 | 85 | Use shorthand properties where possible. 86 | 87 | CSS offers a variety of [shorthand](http://www.w3.org/TR/CSS21/about.html#shorthand) properties (like font) that should be used whenever possible, even in cases where only one value is explicitly set. 88 | 89 | Using shorthand properties is useful for code efficiency and understandability. 90 | 91 | ```css 92 | /* Not recommended */ 93 | border-top-style: none; 94 | font-family: palatino, georgia, serif; 95 | font-size: 100%; 96 | line-height: 1.6; 97 | padding-bottom: 2em; 98 | padding-left: 1em; 99 | padding-right: 1em; 100 | padding-top: 0; 101 | /* Recommended */ 102 | border-top: 0; 103 | font: 100%/1.6 palatino, georgia, serif; 104 | padding: 0 1em 2em; 105 | ``` 106 | 107 | ## Formatting 108 | 109 | ### Declaration Order 110 | 111 | Put declarations in alphabetical order in order to achieve consistent code in a way that is easy to remember and maintain. 112 | 113 | Ignore vendor-specific prefixes for sorting purposes. However, multiple vendor-specific prefixes for a certain CSS property should be kept sorted (e.g. -moz prefix comes before -webkit). 114 | 115 | ```css 116 | background: fuchsia; 117 | border: 1px solid; 118 | -moz-border-radius: 4px; 119 | -webkit-border-radius: 4px; 120 | border-radius: 4px; 121 | color: black; 122 | text-align: center; 123 | text-indent: 2em; 124 | ``` 125 | 126 | ### Block Content Indentation 127 | 128 | Indent all [block content](http://www.w3.org/TR/CSS21/syndata.html#block), that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding. 129 | 130 | ```css 131 | @media screen, projection { 132 | 133 | html { 134 | background: #fff; 135 | color: #444; 136 | } 137 | 138 | } 139 | ``` 140 | 141 | ### Declaration Stops 142 | 143 | End every declaration with a semicolon for consistency and extensibility reasons. 144 | 145 | ```css 146 | /* Not recommended */ 147 | .test { 148 | display: block; 149 | height: 100px 150 | } 151 | 152 | /* Recommended */ 153 | .test { 154 | display: block; 155 | height: 100px; 156 | } 157 | ``` 158 | 159 | ### Separator and Declaration Separation 160 | 161 | End every declaration with a semicolon for consistency and extensibility reasons. 162 | 163 | Always start a new line for each selector and declaration. 164 | 165 | ```css 166 | /* Not recommended */ 167 | a:focus, a:active { 168 | position: relative; top: 1px; 169 | } 170 | 171 | /* Recommended */ 172 | h1, 173 | h2, 174 | h3 { 175 | font-weight: normal; 176 | line-height: 1.2; 177 | } 178 | ``` 179 | 180 | ### CSS Quotation Marks 181 | 182 | End every declaration with a semicolon for consistency and extensibility reasons. 183 | 184 | Use single (`''`) rather than double (`""`) quotation marks for attribute selectors or property values. Do not use quotation marks in URI values (url()). 185 | 186 | ```css 187 | /* Not recommended */ 188 | @import url("//www.google.com/css/maia.css"); 189 | 190 | html { 191 | font-family: "open sans", arial, sans-serif; 192 | } 193 | 194 | /* Recommended */ 195 | @import url(//www.google.com/css/maia.css); 196 | 197 | html { 198 | font-family: 'open sans', arial, sans-serif; 199 | } 200 | ``` 201 | 202 | ## References 203 | 204 | 1 Title 205 | Reference Google HTML/CSS Style Guide 206 | 207 | 208 | 2 Title 209 | Reference W3C CSS Validation Service 210 | 211 | 212 | 3 Title 213 | Reference W3C Markup Validation Service 214 | 215 | 216 | 4 Title 217 | Reference W3C website 218 | 219 | 220 | 5 Title 221 | Reference Web Content Accessibility Guidelines 222 | 223 | 224 | Abbreviations 225 | IMT Information Management and Technology 226 | RNIB Royal National Institute for the Blind 227 | SDP Software Development and Maintenance Process 228 | W3C World Wide Web Consortium 229 | WCAG Web Content Accessibility Guidelines 230 | WAI Web Accessibility Initiative 231 | -------------------------------------------------------------------------------- /software-engineering-policies/CodingStandards/DotNetCodingStandards.md: -------------------------------------------------------------------------------- 1 | # .Net Coding Standards 2 | 3 | .Net code should be in C# using the latest LTS release appropriate to the project. 4 | 5 | The UK Hydrographic Office has adopted the Microsoft C# Coding Conventions: with the following notes and exceptions: 6 | 7 | ## Async methods 8 | 9 | async methods should have an `Async` suffix. e.g. 10 | 11 | ```cs 12 | public Task BuildCatalogueAsync() 13 | ``` 14 | 15 | ## var 16 | 17 | Use `var` unless there is a specific reason not to. 18 | -------------------------------------------------------------------------------- /software-engineering-policies/CodingStandards/JavascriptCodingStandards.md: -------------------------------------------------------------------------------- 1 | # JavaScript Coding Standards 2 | 3 | ## Overview 4 | 5 | These JavaScript standards describe the default usage and configuration of the JavaScript language, and associated tools within the Software Engineering discipline at the UK Hydrographic Office. 6 | 7 | All Software Engineering projects should use these standards by default, however they are not mandatory and alternatives and deviations are permitted, provided that any such alternatives or deviations are fully captured, along with justifications for use, in project documentation. 8 | 9 | Updates to these standards must be agreed and approved by the collective Lead Engineers meeting, and may be applied at any time. 10 | 11 | ## Language Guidelines 12 | 13 | The baseline set of JavaScript language guidelines are given by the Google JavaScript Style Guide, located here: 14 | 15 | ## Exceptions 16 | 17 | There may be exceptions to the guidelines mentioned above. These must be determined on a project-by-project basis, and documented appropriately. 18 | 19 | For secure projects, the style guide above has one immediate exception: the `eval()` function is NOT permitted by default due to the security implications of using that particular function. Further details can be found here: 20 | 21 | 22 | 23 | ## TypeScript 24 | 25 | TypeScript is a strongly-typed variant of JavaScript which benefits from compile-time analysis when developed with some tools. As such, it is seen as the preferred option, especially when developing single-page applications, or other standalone resources. 26 | 27 | ## Tooling 28 | 29 | IDE / Editor 30 | 31 | JavaScript (and TypeScript) can be written with any ASCII editor application. The standard IDE within the UKHO is Microsoft Visual Studio, and this has increased support for TypeScript. However, any editors may be used to write JS/TS. 32 | 33 | ## Linting 34 | 35 | All JavaScript code shall have a linting tool applied in order to conform to good coding practices. The default choice of tool is [ESLint](https://eslint.org/). 36 | 37 | Whilst most of the suggestions made by ESLint are good practice, there may be some which are not appropriate for a project. Wherever any of the linting rules are ignored or overridden, they must be documented along with justification. 38 | 39 | ESLint support is built into Visual Studio, it can be enabled by ticking the checkbox in the `Tools -> Options` menu under `Text Editor -> JavaScript/TypeScript -> Linting`. It is also available for Java development as an Eclipse Tern plugin, and can be integrated with the IntelliJ IDE. Additionally, there is a Visual Studio Code extension. 40 | 41 | Google provide an ESLint configuration supporting the Google JavaScript style guide here: . 42 | 43 | ## Unit Testing 44 | 45 | As per the [Unit Testing Policy](../UnitTesting/UnitTestingPolicy.md), unit testing is required on all applications which includes any that execute JavaScript code. Jest is the chosen unit testing framework for JavaScript, since it is the most widely used, supported, and documented. Jest documentation and guides can be found here . 46 | 47 | Jasmine has been used historically and can be downloaded from This site also contains excellent documentation for writing Jasmine tests, along with add-on modules which increase the capability of the framework (e.g. jasmine-ajax). Jasmine unit tests can be automated by using the Chutzpah JavaScript test runner. 48 | -------------------------------------------------------------------------------- /software-engineering-policies/CodingStandards/PythonCodingStandards.md: -------------------------------------------------------------------------------- 1 | # Python Coding Standards 2 | 3 | ## Purpose and Scope 4 | 5 | These guidelines are written to represent best practices but do not supersede expected personal engineering high standards. 6 | 7 | We utilise coding standards to: 8 | 9 | * Create a consistent look and feel. 10 | * Enabling readers to understand more quickly by making * assumptions based on experience. 11 | * Facilitate changes and maintenance. 12 | * Demonstrate best practice. 13 | * Reduce ambiguities in the ISO auditing process. 14 | 15 | ## Roles and Responsibilities 16 | 17 | Anyone who writes code is responsible for following these guidelines. Code reviews are subject to the following criteria: 18 | 19 | * Code reviews shall take place as part of the Software Development Process (SDP) for safety-critical or Defence work. 20 | * Code reviews should take place as part of the Software Development Process (SDP) for all other work. 21 | 22 | It will be the responsibility of the coder(s) and reviewer(s) to document and demonstrate adherence to the SDP to any internal or external auditors. 23 | 24 | ## Python Coding Conventions 25 | 26 | We follow Python's own in-built coding standards, known as PEP 8. The full PEP 8 Style Guide can be found here: 27 | 28 | There are several Integrated Development Environments (IDEs) which actively monitor code for PEP 8 violations. At the time of writing, JetBrains PyCharm is the recommended IDE for writing Python code. If this IDE cannot be used for any reason, then a command-line tool called Flake8 may be used to check for PEP 8 violations. 29 | 30 | ## Secure Coding Conventions 31 | 32 | Python is an interpreted language, and as such, security flaws may be harder to spot. It is recommended to use a static analysis tool such as SonarQube, or a Python-specific tool such as Bandit () 33 | 34 | OWASP publishes lots of significant guidance around application design and architecture. 35 | 36 | A taxonomy of security errors can be found here: 37 | 38 | ## Type Annotations 39 | 40 | Since Python version 3.5, there has been in-built support for type annotations. Simply put, these provide a mechanism by which to specify the types which a method should be taking in its parameter list, or returning. 41 | 42 | The use of type annotations makes code somewhat more verbose, but arguably more secure and easier to read, review, and maintain. Furthermore, they provide more capable IDEs with a basic form of static type checking (i.e. the ability to point out when an incorrect type is being passed to or returned from a method) prior to runtime. 43 | 44 | ​The official Python standard for Type Annotations can be found here: 45 | 46 | ## Secure Coding Practices 47 | 48 | 1. Validate input. Validate all input from untrusted data sources. Be suspicious of most external data sources, including command line arguments, network interfaces, environmental variables and user controlled files. 49 | 1. Warnings as errors. All IDE warnings should be treated as errors. 50 | 1. Keep it simple. Complex designs lead to an increased likelihood of errors in implementation and configuration. 51 | 1. Default deny. Base access decisions on permission rather than exclusion. 52 | 1. Adhere to the principle of least privilege. A process should execute with the least set of privileges required to complete the job. 53 | 1. Sanitize data sent to other systems. Sanitize all data passed to subsystems. The subsystem may not be aware of the context in which a call to it is being made, therefore as the calling process understands the context, it is responsible for sanitizing the data. 54 | 1. Define security requirements. Identify and document security requirements early in the development life cycle and ensure that they are documented and evaluated for compliance. 55 | 1. Do not use the eval() or exec() methods. Both of these built-in methods allow dynamic execution of Python code. Their use leaves your code open to numerous security vulnerabilities, and as such, they should be prohibited in code used in safety-critical or Defence systems. 56 | 57 | ## Python versions and Legacy Code 58 | 59 | Python 2 reached end-of-life on January 1st 2020, and will not be maintained past that point. As a result, Python 3 **shall** be used wherever possible. 60 | 61 | Any Python 2 code will have to be re-written before 2020 to avoid technical debt. Exceptions include where a system only supports Python 2 (e.g. ESRI ArcGIS), but these must be upgraded to Python 3 as soon as possible. 62 | 63 | ## Unit Testing Requirements and Guidelines 64 | 65 | Since Python is an interpreted language, there are no compile-time warnings. This means that Python code is more susceptible to bugs and vulnerabilities than many compiled languages. For this reason, unit test coverage must be as close to 100% as possible, with a minimum of 95% coverage. 66 | 67 | It is recommended to use libraries such as Hypothesis to aide in testing validation cases. 68 | 69 | It is recommended to use the Python Coverage library to indicate the completeness of test code coverage. 70 | 71 | Note that if using the Python Coverage tool, the reported figure will indicate the percentage of lines of code executed, and not necessarily the percentage of lines of code tested. It is the responsibility of the coder(s) to ensure that sufficient testing has taken place. 72 | 73 | With this in mind, it is recommended that the unit tests cover the following areas in order to attain sufficiently high code coverage: 74 | 75 | * Has each unit been tested with good inputs? 76 | * Has each unit been tested with bad inputs? 77 | * Have each of the branching conditions in the unit been tested? 78 | * Have any sub-calls been tested? 79 | * Have the parameters passed to the sub-calls been tested? 80 | * Has the return from the unit been tested? 81 | * Have any error / exception conditions been tested? 82 | * Note: There is a Python library called Hypothesis which provides a mechanism for data-driven testing, and will generate many sets of test data for each of your unit tests. See 83 | 84 | ## Productionisation Guidelines 85 | 86 | Productionisation of Python code is subjective and depends upon the uses to which the software will be put. Broadly speaking, it involves (but is not limited to) the following: 87 | 88 | * Ensure that the code follows coding guidelines and standards. For Python, this is PEP 8. 89 | * Ensure that the code has unit tests which provide 100% code coverage. 90 | * Ensure that the code has been peer-reviewed for non-testable aspects such as maintainability or extensibility. 91 | * Ensure that the code has been reviewed for security vulnerabilities. 92 | * Ensure that the deployment mechanism is reliable, repeatable, and consistent. 93 | * Ensure that appropriate user and technical documentation has been written. 94 | -------------------------------------------------------------------------------- /software-engineering-policies/CodingStandards/README.md: -------------------------------------------------------------------------------- 1 | # Coding Standards Policy 2 | 3 | ## Overview 4 | 5 | These Coding Standards describe the default usage and configuration of their language, and associated tools within the Software Engineering discipline at the UK Hydrographic Office. 6 | 7 | All Software Engineering projects should use these standards by default, however they are not mandatory and alternatives and deviations are permitted, provided that any such alternatives or deviations are fully captured, along with justifications for use, in project documentation. 8 | 9 | Updates to these standards must be agreed and approved by the collective Lead Engineers meeting, and may be applied at any time. 10 | -------------------------------------------------------------------------------- /software-engineering-policies/Containers/ContainerBestPractices.md: -------------------------------------------------------------------------------- 1 | # Container Best Practices 2 | 3 | ## Dockerfile Best Practices 4 | 5 | Docker provide a series of best practices for writing and developing Dockerfile’s. These are: 6 | 7 | * Best practices for [writing a Dockerfile](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/). 8 | * Best practices for [developing with Docker](https://docs.docker.com/develop/dev-best-practices/). 9 | * Best practices for [secure development with Docker](https://docs.docker.com/develop/security-best-practices/). 10 | 11 | The following items supersede these best practices: 12 | 13 | * Where a container needs to use secrets and passwords, these should be injected into the container via environment variables defined in the Dockerfile and should be encrypted at a minimum. 14 | * Dockerfile’s should be linted to detect issues and vulnerabilities 15 | * Aim to use minimal dependencies, such as [distroless container base](https://github.com/GoogleContainerTools/distroless). 16 | * Avoid defining unnecessary privileges and avoid running as root. 17 | * Ensure there is a well-established process for updating dependencies. 18 | * Where both suitable and possible, leverage [multi-stage builds](https://docs.docker.com/build/building/multi-stage). 19 | * The UK Hydrographic office have a number of [approved images at DockerHub](https://hub.docker.com/u/ukhydrographicoffice) and it is recommended new images are based on these. The Dockerfile files for these images are stored within the [UKHO dockerimages repo on GitHub](https://github.com/UKHO/dockerimages). 20 | 21 | ## Container Deployment Best Practices 22 | 23 | ### Must Do 24 | 25 | * Where applicable at deployment, secrets must be stored via Azure KeyVault, AWS Secrets Manager, etc. 26 | * The containers resources, limits and requests for CPU and Memory consumption must be defined for deployment 27 | * Containers deployments and deployment environment must be configured using infrastructure as code. 28 | * Deployments must include a means to monitor the health of the container. For example, when using Kubernetes, configure readiness and liveliness probes. 29 | * Environments above Dev must have HTTPS enforced and HTTP to HTTPS redirects enabled. 30 | * Logs generated by containers must be consumed. 31 | * Access to the underlying infrastructure running the container images must be blocked in all environments above Dev. 32 | * Container images must be scanned by a vulnerability scanning tool. 33 | * Container deployments must not become a persistance data store or silo. 34 | 35 | ### Should do 36 | 37 | * Microservices and containers should communicate only with services and ports they need to. 38 | * Access Policies and Network Security Groups should be applied. 39 | * Container deployments should be isolated using Namespaces. 40 | * Monitoring solution should be in place for deployed containers. For example, ELK (.Net), EFK (Java) stacks, Grafana, Prometheus etc. 41 | * Automated deployments should be used on container image version increments within the container registry. 42 | 43 | ### Could do 44 | 45 | * Native built in support within visual studio for Docker could be used for development and testing. 46 | * Docker Compose could be utilised to stub other dependencies that the container uses. 47 | 48 | ## Best practice guides 49 | 50 | * sysdig blog [post]() on practices. 51 | -------------------------------------------------------------------------------- /software-engineering-policies/Containers/ContainerPolicy.md: -------------------------------------------------------------------------------- 1 | # Container Policy 2 | 3 | ## Motivation 4 | 5 | Containers are in use in Data Science and Software Engineering, in all environments of development, test and production. This policy defines the secure development and deployment for all current and future usage. 6 | 7 | ## Policy 8 | 9 | * Containers are a potential option for architects to utilise (a tool in the toolbox). 10 | * Consideration should be made around why we want to utilise containers. 11 | * Consideration should be made around who will inherit the environments at the outset. i.e. is there expertise in how manage the hosting environment? 12 | * Utilisation of Containers in development and test environments is acceptable without APF review. 13 | * In the Software Engineering department, deployment of containers into live will need to be approved by The Head of Software Engineering in conjunction with the Principal and Lead Software Engineers, until agreement is reached via APF forum. 14 | * Containers are a core software and test engineering tool. 15 | * [Container best practices](./ContainerBestPractices.md) should be adopted by all teams using containers. 16 | * The Lead Software Engineer for each team is responsible for ensuring that this policy is adhered. 17 | 18 | ## Security 19 | 20 | Use of containers provides a convinient way for engineering teams to develop and deploy applications in a robust way without the overhead of always having to acomodate the hosting platform. However this can come at a price due to security being shifted more towards the development team rather than the operations teams. To ensure we are doing the best we can when it comes to containerisation safety, the following should be adhered to. 21 | 22 | ### Container Image 23 | 24 | The container image being selected should be the leanest image for what you require. This means using an base image that contains the minimum amount of dependencies required to run your application. What this does is reduce the attack surface a threat actor has to perform malicious actions within your service. It also has the added benefit of reduced container image size as we are not holding dependencies we are not using. 25 | 26 | As a recommendation whenever picking a container image, we should start with the alpine version first and only moving to a fuller version if we need to make too many modifications to the dockerfile. 27 | 28 | ### User Access 29 | 30 | The default user on a Linux container image is a root user which can be where all problems start if an attack is made on your service. To combat this it is advised that a non-root user is created that is only given access to your service code. If developing in Dotnet 8.0 this is [provided for you](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-8/containers#non-root-user). 31 | 32 | ### Container Scanning 33 | 34 | It is important before we release any containers into an environment that we perform a vulnerability scan to ensure that 3rd party dependencies are not going to be the weak link in our security chain. Therefor using the tool of choice performing a scan and not allowing anything high or above is the best way to protect ourselves. Anything found when scanned at this level should stop the pipeline and investigated for potential upgrades/fixes. If no fixes are found and you feel that this will not affect your system, you can reach out the Security team or your Lead Developers for advice on mitigation/suppression of these issues. 35 | 36 | ## Exclusions 37 | 38 | This policy does **not** cover the following items: 39 | 40 | * Docker Desktop - which is a licensed product. Approval and license acquisition should follow the standard UKHO policy. 41 | * Kubernetes - the focus of this document is on containers and not their hosting environment. 42 | -------------------------------------------------------------------------------- /software-engineering-policies/DefectManagement/DefectManagementPolicy.md: -------------------------------------------------------------------------------- 1 | # Defect Management Policy 2 | 3 | An effective Defect Management workflow **must** be in place for all teams. The Defect Management workflow is to be created and maintained by each team, working with the **Test Leads** to ensure it meets the requirements outlined below. 4 | 5 | The Defect Management workflow *should* include the following: 6 | 7 | - The definition of a defect - what is a defect? 8 | - Minimum detail required when logging a defect 9 | - Where, when and how defects should be logged 10 | - Defect Triage process (Does it contain enough detail?, Is it a defect?, Severity, When should it be fixed?) 11 | - Defect closure process 12 | 13 | It is the team's responsibility to ensure that the Defect Management workflow is adhered to. 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /software-engineering-policies/FrontEnd/FrontEndPolicy.md: -------------------------------------------------------------------------------- 1 | # Front End Policy 2 | 3 | ## Design System 4 | 5 | At the UKHO we have an [in house design system](https://github.com/UKHO/admiralty-design-system). 6 | 7 | The design system repository is public which means that anyone in the world can view the code and commit history. We are currently not taking any contributions from people outside the UKHO and offer no support to external developers. 8 | 9 | For internal developers we offer support through the usage of Github issues. There are two types of issue template, bug and feature request, these are templates that will guide developers to provide us with enough information to work on the issue. 10 | 11 | The design system is supported primarily by the UX Champion team, however they only have part of their time dedicated to support, therefore if requests are urgent if possible we encourage teams to try and work through the issue themselves with guidance from the UX champions. 12 | 13 | All new projects that have UI's and customer facing elements should consider using the design system within their project in order to make our products have a consistent look and feel. It also offers the benefits of familiarity to developers and confidence of the elements working together. 14 | 15 | ## Angular 16 | 17 | Currently at the UKHO our first choice for language when building websites is Angular. This is currently where our specialties lie but this could change and evolve overtime depending on current recruitment trends. 18 | 19 | It is not a hard and fast rule, if teams have a technology that they are more familar with then discussions should be carried out to determine a more appropriate approach weighing up the upskilling time of the support team vs the speed of development time. 20 | 21 | ## User Interaction Designers 22 | 23 | If a project will contain a user facing interface, we encourage all teams to reach out to User Experience Team. This is a team of full time designers who have a skill set in taking user needs, testing them with customers and users through various designs and then presenting them back to the team. The UKHO has a strong belief of customer centric design, so it is important that our designs are tested with real users to give them what they really want, not what we think they want. 24 | -------------------------------------------------------------------------------- /software-engineering-policies/InclusiveLanguage/InclusiveLanguagePolicy.md: -------------------------------------------------------------------------------- 1 | 2 | # Inclusive Language Policy 3 | 4 | This document will outline how software development teams at the UKHO can ensure that code and documentation is written with diversity and inclusion in mind. 5 | 6 | It is not definitive and is likely to be updated as best practices evolve. 7 | 8 | ## Applicability 9 | 10 | This policy applies to anyone contributing to UKHO code or documentation in public or private repositories. 11 | 12 | ## Introduction 13 | 14 | The UKHO embraces diversity and promotes inclusion and equality of opportunity. 15 | 16 | Language plays a critical role in fostering an inclusive environment and as such, the language used in the documentation and code managed by our software development teams should reflect these values also. 17 | 18 | We should avoid use of language that is discriminatory, condescending or where it might represent: 19 | 20 | - Age bias 21 | - Culture bias 22 | - Disability bias 23 | - Ethnic slurs 24 | - Gender bias 25 | - Gender-specific language 26 | - Racial bias 27 | - Sexual orientation bias 28 | 29 | Some terminology might be normalized on the technical level but loaded at societal level. As such, we should avoid referring to people using divisive wording and avoid using loaded terminology where unnecessary to describe technical concepts. Examples include: 30 | 31 | 32 | - master/slave 33 | - blacklist/whitelist 34 | - sanity check 35 | - dummy 36 | 37 | 38 | ## Application in new projects 39 | 40 | All new documentation and code should be inclusive and facilitate diversity. Contributing authors are strongly encouraged to use neutral terms and avoid exclusionary language, to ensure the most inclusive environment possible. 41 | 42 | A link to this policy should be provided from the CONTRIBUTING.md file. 43 | 44 | ### Default branch naming on GitHub (new projects) 45 | 46 | From 1 October 2020, newly created repositories automatically set main as the default branch in place of master. 47 | 48 | ### Default branch naming on Azure DevOps (new projects) 49 | 50 | This will automatically be set to *main* in the Azure DevOps cloud service but will need to be changed manually after creating a new repository. 51 | 52 | ## Application in existing projects 53 | 54 | When working in an existing codebase, teams should be alert to opportunities to update the language used in documentation and code. A link to this policy should be provided from the CONTRIBUTING.md file at the same time. 55 | 56 | ### Default branch naming on GitHub (existing projects) 57 | 58 | GitHub has made it straightforward to change existing repositories without any disruption to work. Teams should ensure that the process of renaming the default branch to *main* has been completed. 59 | 60 | ### Default branch naming on Azure DevOps (existing projects) 61 | 62 | Microsoft have no plans to ease the renaming process so it is up to teams to manage if and when it is practical to do so, taking into consideration any future plans to migrate to GitHub. 63 | 64 | ## Automating checks on documentation 65 | 66 | It may be helpful in some cases to automate checks on technical documentation written in markdown or plaintext. While we wait for support on tooling to come from the [Inclusive Naming Initiative](https://inclusivenaming.org/), we have found Alex.js to be fairly helpful in some simple use cases. 67 | 68 | ### Alex.js 69 | 70 | - Source: https://github.com/get-alex/alex 71 | - Usage: Automated checks in CI Build and integration with editors / IDEs. 72 | 73 | > Whether your own or someone else’s writing, alex helps you find gender favoring, polarizing, race related, religion inconsiderate, or other unequal phrasing in text. 74 | 75 | Alex has integrations available for numerous editors, including VS Code. This is a good place to enable the full set of rules for equality and profanity. 76 | 77 | For CI builds, particularly on existing projects, the focus might be on a subset of the rules, to identify the loaded terminology identified above. Alex.js has been applied to [UKHO docs](https://github.com/ukho/docs) via GitHub Actions with a small subset of rules. An Action is available from the marketplace that comments on Pull Requests, which requires additional setup with a token, so instead, we execute Alex directly via Node. 78 | 79 | Contact @benbhall with any queries about the Alex.js. 80 | 81 | ## Checking code 82 | 83 | Currently, the best way to check you are using inclusive language in your code is to search for known offending terminology. 84 | 85 | 86 | For example, you might search code locally for use of the words master, slave, blacklist or whitelist using a regular expression: 87 | 88 | 89 | `((black|white)[_-]?(list)+)|master|slave` 90 | 91 | ## Other tools 92 | 93 | In Microsoft Office it is possible to enable writing style checks for inclusive language. Exactly how you find the setting depends on the version but it is typically under options for grammar and proofing. Again, depending on your version, you might only be able to enable checks on gender bias. Newer versions will offer many more. As this is a setting for MS Office, you will benefit from the checks across the suite, including Outlook. 94 | 95 | Checking for bias in job adverts with https://joblint.org/. 96 | 97 | ## Further reading 98 | 99 | - [Inclusive Naming Initiative](https://inclusivenaming.org/) 100 | - The IETF (Internet Engineering Task Force) have collated a list of terms with [suggested alternatives](https://github.com/ietf/terminology). 101 | - Article by NCSC (National Cyber Security Centre UK) on [their changes](https://www.ncsc.gov.uk/blog-post/terminology-its-not-black-and-white). 102 | - Some background context on Terminology, Power and Oppressive Language, in a [draft submitted to the IETF](https://tools.ietf.org/id/draft-knodel-terminology-04.html). 103 | - Specific guidance on documenting accessibility [by Google](https://developers.google.com/style/inclusive-documentation#about-disability-and-accessibility). 104 | -------------------------------------------------------------------------------- /software-engineering-policies/Induction/LeadDeveloperInduction.md: -------------------------------------------------------------------------------- 1 | # Induction sheet for new Lead Developers 2 | 3 | ## Security 4 | 5 | By default, the Lead Developer will also be the Security Advisor. If this is the case: 6 | 7 | * The lead needs to be walked through the Secure Development Policy by the Software Engineering Team Manager or another Security Advisor. 8 | * The team's documentation needs to be updated with the identity of the new Security Advisor. 9 | * The lead should self-certify the team against the Secure Development Policy and send the results to the Software Engineering Team Manager. 10 | 11 | ## Policies 12 | 13 | The Lead Developer is accountable for the team following all the engineering team's policies. The Software Engineering Team Manager will: 14 | 15 | * Show the location of the policies 16 | * Describe each policy 17 | * Clarify the Lead's accountability towards the policies 18 | * Explain how to change the policies 19 | * Explain coding in the open principals 20 | 21 | ## Groups and contacts 22 | 23 | * Invite to the Lead's meeting 24 | * Introduce to the Testing practice (e.g. invite to Test Practice monthly meeting) 25 | * Make sure they are invited to the sprint reviews of other teams where appropriate 26 | 27 | ## Skills and activities 28 | 29 | * Discuss with line manager the skills required to do the role. Draw up a development plan. 30 | * Discuss use of time with line manager. Set expectations around amount of coding that is likely. 31 | * Meet with SA to establish areas of responsibility between the SA and the lead 32 | 33 | ## Support network 34 | 35 | Conversation with line manager around the following: 36 | 37 | * Would they benefit from a mentor? 38 | * Sit down with another lead developer to undertsand role 39 | * How can they obtain feedback? 40 | * Discuss imposter syndrome, expectations of knowing everything 41 | -------------------------------------------------------------------------------- /software-engineering-policies/Induction/SettingUpYourMSDN.md: -------------------------------------------------------------------------------- 1 | # Setting up your MSDN right 2 | 3 | You may be purchased an MSDN license ranging from MSDN Platforms up to Enterprise, depending on your needs. One of the benefits of an MSDN license is linked access to Azure Services and the option to spend monthly azure credits. 4 | 5 | One of the main tools we use for source control is GitHub and Workflow using Azure DevOps. 6 | 7 | MSDN + GitHub will be purchased for anyone with Pro and Enterprise Licenses. 8 | 9 | ## Setup for GitHub 10 | 11 | In order to leverage the MSDN license against your github profile, you can do one of two things: 12 | 13 | - The first is to create a github account linked to your work email, your MSDN is linked to your work email, so once the two find each other your account will instantly upgrade. 14 | - The second option is to add your work email as an extra email on your [github profile](https://github.com/settings/emails), the act of adding your work email to your profile does the same thing as setting up a work specific account. 15 | 16 | There are some caveats; MSDNs can only be leveraged against members of our organisation and only if their license has been purchased by the MoD, 3rd party license cannot be leveraged. 17 | 18 | Staff who are BPSS will not link to an MSDN license. However performing the above will allow your account to instantly link once you get clearance and become a member of the organisation. 19 | 20 | ## Setup for Azure DevOps 21 | 22 | Your MSDN license gives you acccess to any Azure DevOps organisations, this works against your work email to begin with. browsing to [https://my.visualstudio.com/subscriptions](https://my.visualstudio.com/subscriptions), provides the option of adding an alternative account. This should primarily be your admin account, doing this will allow you to leverage the same benefits against that account. 23 | -------------------------------------------------------------------------------- /software-engineering-policies/InfrastructureAsCode/terraform.md: -------------------------------------------------------------------------------- 1 | # Infrastructure as Code: Terraform 2 | 3 | Terraform is our tool of choice, and should be considered in the first instance. 4 | 5 | Most standards and practices at the UKHO are covered in the training courses we provide around the use of Terraform. 6 | 7 | Videos and a presentation can be found in the **Software Engineering Team > Training Channel**. Online resources provided by [terraform.io](https://www.terraform.io/) are also very useful. 8 | 9 | ## Avoid adding local modules 10 | 11 | Holding modules in the same repository as the project reduces it's audience. It is likely that you might be tempted to copy the modules you created in the previous project to your new one. 12 | 13 | Most modules can be written in a relative IP lossless way, to avoid attack vectors or concerns around security. Using public modules makes them easy to find and reuse, adhering to a standard naming convention makes them easy to find in GitHub, and creating releases allows for ease of specifying a version to use. 14 | 15 | Each module should be hosted it's own GitHub repo to keep the download size small, following the convention mentioned in the [template project for terraform](https://github.com/UKHO/terraform-module-template) modules. Using the terraform module template will create a repo with the contents setup as standard. Review the naming convention guide linked on the readme of the template to see how you might go about naming the module. 16 | 17 | Using the same naming convention allows for a [simple search for tfmodule](https://github.com/UKHO?q=tfmodule&type=all&language=&sort=) in GitHub to show a list of all the modules that are available and how to use them. 18 | 19 | ## Versioning modules 20 | 21 | Semantic versioning is used. The main branch is used to control the latest releases. When testing an addition, tagging the feature branch with a pre-release tag is a beneficial way to identify this. A main release will be versioned as 0.1.0 whereas the pre-release will be versioned 0.1.0-alpha.1. 22 | 23 | A new pre-release will be needed for each change intended for testing. 24 | 25 | ## Referencing modules in code 26 | 27 | Modules in GitHub can be referenced easily using a source qualifier for GitHub. The ref pointer in the source url refers to the tag / release version you intend to use. 28 | 29 | ```terraform 30 | module "eventhub" { 31 | source = "github.com/ukho/tfmodule-azure-event-hub?ref=0.4.0" 32 | providers = { 33 | azurerm.src = azurerm.alias 34 | } 35 | 36 | servicename = var.servicename 37 | deploy_environment = var.deploy_environment 38 | role = var.role 39 | resource_group_name = var.resource_group_name 40 | resource_group_location = var.resource_group_location 41 | } 42 | ``` 43 | -------------------------------------------------------------------------------- /software-engineering-policies/NFRs/NFRPolicy.md: -------------------------------------------------------------------------------- 1 | # NFRs 2 | 3 | Non functional requirements must be seen as everyone's responsibility. 4 | 5 | ## Scope 6 | 7 | This policy seeks to ensure that non functional requirements are present and delivered as part of a piece of work undertaken by a delivery team. 8 | 9 | Please also see the [UKHO NFR definition](https://ukho.sharepoint.com/sites/eagwiki/Pages/NFR%27s.aspx). 10 | 11 | ## Implementation of policy 12 | 13 | Delivery teams should ensure NFRs are present when starting a new piece of work. If this is not the case, the solution architect aligned with the team should be tasked with discovering and providing the relevant NFRs. If the team does not know who their solution architect is, they should consult with the architecture practice head. 14 | 15 | The intended support team / Support Principal may well have their own set of NFRs for the impacted service(s) and should be consulted! 16 | 17 | During development the NFRs may change as the solution progresses, but fulfilling the NFRs must **not** be de-prioritised or disregarded. 18 | 19 | ## Signing off Project 20 | 21 | Demonstrating that the NFRs have been satisfied **must** be included as part of signing off a piece of work. 22 | 23 | ## Support team handover 24 | 25 | Where a piece of work undertaken by a delivery team is to be handed to a support team. The NFRs must be respected by the delivery team. 26 | 27 | The support team have the authority to reject the delivery until their NFRs are satisfied. 28 | -------------------------------------------------------------------------------- /software-engineering-policies/NamingConventions/NamingConventions.md: -------------------------------------------------------------------------------- 1 | # Naming Conventions 2 | 3 | ## Overview 4 | 5 | Where possible we want to use the same names for things that are common across many implementations, easier maintenance. 6 | 7 | ## Aim 8 | 9 | To set out naming conventions that have been agreed between SE, DDC & Tech Ops and to apply them as consistently as possible. We do not intend to force retrofit on existing implementations. It is understood that there may be reasons for deviating from the conventions and we cannot cover all eventualities. 10 | 11 | ## Conventions 12 | 13 | For security we have kept our naming convention documentation `internal` to prevent conventions from being used as a potential attack vector. 14 | 15 | See [Naming Conventions](https://github.com/UKHO/docs-internal/blob/main/NamingConventions/NamingConventions.md). 16 | -------------------------------------------------------------------------------- /software-engineering-policies/OpenSourceContribution/OpenSourceGovernanceChecklist.md: -------------------------------------------------------------------------------- 1 | # Open Source Governance Checklist 2 | 3 | ## Identifier 4 | 5 | (e.g. repo name) 6 | 7 | ## Technical owner 8 | 9 | The lead responsible for the repo 10 | 11 | ## Description of functionality 12 | 13 | Must contain enough detail to allow assessment of whether it contains intellectual property that we need to protect. 14 | 15 | ## Security 16 | 17 | *How has security been considered?* 18 | 19 | Has application code been scanned with security tooling and issues corrected? 20 | > This must be done for code supported by our SAST tooling 21 | 22 | Has the application been threat modelled during development and the evidence captured within TFS (or similar)? 23 | > Threat modelling must be carried out for all application code, this evidence needs to be reviewed by expert or lead engineer 24 | 25 | Has the code been double-checked for security credentials, keys etc.? 26 | > Give details of who has double-checked the code 27 | 28 | Is a disclosure process in place and linked from the codebase? 29 | > Use the standard disclose text 30 | 31 | ## Quality 32 | 33 | *How has code quality been considered?* 34 | 35 | Does the quality of the code reflect our ambitions for high quality code, in terms of being clean, well-tested etc. 36 | > Correct answer = yes! 37 | 38 | Has all code been reviewed? 39 | > Correct answer = yes! 40 | 41 | Has the open-sourced codebase had its history removed? If not, have all check-in comments been reviewed? 42 | > Describe the steps taken to prevent inadvertent disclosed in comments / etc. 43 | 44 | Does the codebase contain all documentation and configuration elements required to build and verify the software? 45 | > A user should be able to build / run tests etc. based on what is in the repo 46 | 47 | ## Contributions 48 | 49 | *Has the handling of contributions considered?* 50 | 51 | Are contributions explicitly encouraged in the codebase 52 | > For example, have you enabled the use of issues and provided a CONTRIBUTING.md? 53 | > Think very carefully before inviting change, as you will then have to answer 'yes' to the next two questions 54 | 55 | Is a process for responding to issues defined? 56 | > Describe in detail the process by which you are going to ensure that issues are responded to in a timely manner 57 | 58 | How is this process resourced? 59 | > Describe how you have made sure that time is available to carry out the process described above. For example, has the relevant manager agreed for time for time to spent on this? 60 | -------------------------------------------------------------------------------- /software-engineering-policies/PackageAdoption/PackageAdoptionChecklist.md: -------------------------------------------------------------------------------- 1 | # Package Adoption Checklist 2 | 3 | ## Prompts 4 | 5 | ### Project 6 | 7 | - Does the package already have a dedicated Azure DevOps project? 8 | - Does the size and/or significance of the package justify a dedicated project? 9 | 10 | ### Pipeline 11 | 12 | - Does a pipeline exist? 13 | - Is it in Azure DevOps? 14 | - Does it include Static Application Security Testing (SAST)? 15 | - Does it include dependency checking? 16 | 17 | ### Documentation 18 | 19 | - Does the documentation accurately reflect the state of the package? 20 | 21 | ### Code 22 | 23 | - Is the code base in a language that the support team is familiar with? 24 | - Is the code at a version support by the language provider e.g. LTS for .NET? 25 | - Does logging meet the logging policy requirements? 26 | - Is adequate testing in place? 27 | 28 | ### Backlog 29 | 30 | - Does a backlog exist? 31 | - Is it managed in Azure DevOps, either directly or via automated synchronisation? 32 | 33 | ## Identified Tasks 34 | 35 | | Initial Adoption | 36 | | ---------------- | 37 | | *Example: Create Azure DevOps project* | 38 | | *Example: Set up SAST in pipeline* | 39 | 40 | | Ongoing Maintenance | 41 | | ------------------- | 42 | | *Example: Monitor the language provider versioning and upgrade the package appropriately* | 43 | | *Example: Be alerted to vulnerable dependencies* | 44 | | *Example: Maintain a changelog for consuming teams* | 45 | -------------------------------------------------------------------------------- /software-engineering-policies/PackageAdoption/PackageAdoptionGuidance.md: -------------------------------------------------------------------------------- 1 | # Package Adoption Guidance 2 | 3 | ## Process Flow 4 | 5 | ```mermaid 6 | graph TD 7 | Start([Start]) --> I1[External stakeholder identifies a package to be adopted] 8 | Start --> I2[Team identifies a package to be adopted] 9 | I1 --> E1[/Package is evaluated for adoption\] 10 | I2 --> E1 11 | E1 --> P1 12 | E1 --> D1 13 | E1 --> C1 14 | E1 --> B1 15 | subgraph Pipeline 16 | P1{Does a pipeline exist?} 17 | P1 -->|Yes| P2{Is the pipeline
in Azure DevOps?} 18 | P2 -->|Yes| P3{Does it include SAST?} 19 | P3 -->|Yes| P4{Does it include
dependency checking?} 20 | P1 -->|No| P5[Specify work to add pipeline] 21 | P2 -->|No| P6{Can it be
migrated to
Azure DevOps?} 22 | P6 -->|Yes| P7[Specify work to migrate pipeline] 23 | P6 -->|No| P8[Consider why the package is using
non-standard deployment and
determine if we can support it] 24 | P3 -->|No| P9[Specify work to
add SAST] 25 | P4 -->|No| P10[Specify work to
add dependency checking] 26 | end 27 | subgraph Documentation 28 | D1{Does the documentation
accurately reflect the current
state of the package?} 29 | D1 -->|No| D2[Specify work to update documentation] 30 | end 31 | subgraph Code 32 | C1{Is the code base in
a language that the support
teams are familiar with?} 33 | C1 -->|Yes| C2{Is the code at a version
supported by the language
provider e.g. LTS for .NET?} 34 | C2 -->|Yes| C3{Does logging meet the
logging policy requirements?} 35 | C3 -->|Yes| C4{Is adequate
testing in place?} 36 | C1 -->|No| C5[Consider why this package is using
a non-standard language and
determine if we can support it] 37 | C2 -->|No| C6[Specify work to
update to current version] 38 | C3 -->|No| C7[Specify work to
refactor logging] 39 | C4 -->|No| C8[Specify work to
add tests] 40 | end 41 | subgraph Backlog 42 | B1{Does a backlog exist?} 43 | B1 -->|Yes| B2{Is it managed
in Azure DevOps?} 44 | B2 -->|Yes| B5[Specify work to transfer
backlog to team] 45 | B1 -->|No| B3[Specify work to
create backlog] 46 | B2 -->|No| B4{Can it automatically
sync with Azure DevOps?} 47 | B4 -->|Yes| B6[Specify work to set up sync] 48 | B4 -->|No| B7[Consider why this package is using
a non-standard backlog and
determine if we can support it] 49 | end 50 | E2[\Package evaluation is documented in an Adoption Checklist/] 51 | P5 --> E2 52 | P7 --> E2 53 | P9 --> E2 54 | P10 --> E2 55 | D2 --> E2 56 | C6 --> E2 57 | C7 --> E2 58 | C8 --> E2 59 | B3 --> E2 60 | B5 --> E2 61 | B6 --> E2 62 | E2 --> E3[Package is proposed through Support Committee for adoption] 63 | E3 --> E4[Team accepts package and adds adoption PBIs to their backlog] 64 | E4 --> End((End)) 65 | ``` 66 | -------------------------------------------------------------------------------- /software-engineering-policies/PackageAdoption/PackageAdoptionPolicy.md: -------------------------------------------------------------------------------- 1 | # Package Adoption 2 | 3 | ## Overview 4 | 5 | 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. 6 | 7 | ## Aim 8 | 9 | This policy aims to set out how such packages can be "adopted" so that they are receiving the appropriate level of development attention and maintenance whilst exposing to the business the amount of work involved for the adopting team, both in terms of bringing the package to an acceptable state for initial adoption and ongoing capacity impact of taking on the maintenance. This applies to both currently orphaned packages and those that might be orphaned in the future by business change to teams. 10 | 11 | ## Methodology 12 | 13 | The [guidance](PackageAdoptionGuidance.md) shows a flowchart of the adoption process. At a high level, the following steps should be undertaken when a package that requires adoption is identified: 14 | 15 | 1. Analysis to quantify the amount of work involved in adoption using the flowchart process 16 | 2. Analysis outcomes recorded in an [adoption checklist](PackageAdoptionChecklist.md) 17 | 3. Analysis outcomes presented to the Support Committee and package proposed for adoption 18 | 4. A team accepts the package for adoption and creates stories based on the analysis outcomes 19 | -------------------------------------------------------------------------------- /software-engineering-policies/PairProgramming/PairProgrammingPolicy.md: -------------------------------------------------------------------------------- 1 | # Pair Programming Policy 2 | 3 | ## Guide 4 | 5 | ### Overview 6 | 7 | Most development activities will benefit from the collaboration of two or more colleagues working together. This practise reduces errors, encourages creativity, enhances problem solving and promotes knowledge sharing between colleagues. 8 | 9 | ### Policy 10 | 11 | Paired working is the preferred approach for any organisational activity that suits this style of working. Teams should consider each activity that it undertakes and apply paired working if appropriate and practical to do so. 12 | 13 | ### Advice 14 | 15 | Activities which may suit a paired working approach might include the creation of software, troubleshooting some issues and releasing new software to the live environment. Activities which are less likely to suit a paired approach might include reviewing code generated in a pull request or researching issues to solve a specific problem. 16 | 17 | ## Verify 18 | 19 | Teams consider each activity that it undertakes and apply paired working if appropriate and practical to do so. 20 | 21 | -------------------------------------------------------------------------------- /software-engineering-policies/PublicRadar.csv: -------------------------------------------------------------------------------- 1 | "name","ring","quadrant","isNew","description" 2 | ".Net Core","Adopt","Frameworks and Libraries","FALSE","None" 3 | "Net Full-Framework","Adopt","Frameworks and Libraries","FALSE","None" 4 | "WPF","Adopt","Frameworks and Libraries","FALSE","None" 5 | "Spring","Adopt","Frameworks and Libraries","FALSE","None" 6 | "Selenium","Adopt","Frameworks and Libraries","FALSE","None" 7 | "Angular","Adopt","Frameworks and Libraries","FALSE","None" 8 | "Playwrite","Adopt","Frameworks and Libraries","FALSE","None" 9 | "OpenLayers","Adopt","Frameworks and Libraries","FALSE","None" 10 | "NServiceBus","Adopt","Frameworks and Libraries","FALSE","None" 11 | "WPF","Hold","Frameworks and Libraries","FALSE","None" 12 | "WCF","Hold","Frameworks and Libraries","FALSE","None" 13 | "Esri ArcMap and ArcGIS Server","Adopt","Infrastructure and tools","FALSE","None" 14 | "Azure","Adopt","Infrastructure and tools","FALSE","None" 15 | "AWS","Adopt","Infrastructure and tools","FALSE","None" 16 | "GCP","Adopt","Infrastructure and tools","FALSE","None" 17 | "Visual Studio","Adopt","Infrastructure and tools","FALSE","None" 18 | "IntelliJ and PyCharm","Adopt","Infrastructure and tools","FALSE","None" 19 | "Postman","Adopt","Infrastructure and tools","FALSE","None" 20 | "Coverity","Adopt","Infrastructure and tools","FALSE","None" 21 | "Kubernetes","Adopt","Infrastructure and tools","FALSE","None" 22 | "Terraform","Adopt","Infrastructure and tools","FALSE","None" 23 | "Docker","Adopt","Infrastructure and tools","FALSE","None" 24 | "Azure Pipelines","Adopt","Infrastructure and tools","FALSE","None" 25 | "Azure App Service","Adopt","Infrastructure and tools","FALSE","None" 26 | "Azure Application Gateway","Adopt","Infrastructure and tools","FALSE","None" 27 | "Azure Event Hub","Adopt","Infrastructure and tools","FALSE","None" 28 | "Azure Function Apps","Adopt","Infrastructure and tools","FALSE","None" 29 | "Azure DevSpaces","Adopt","Infrastructure and tools","FALSE","None" 30 | "Azure Kubernetes Service","Adopt","Infrastructure and tools","FALSE","None" 31 | "GitHub","Adopt","Infrastructure and tools","FALSE","None" 32 | "Azure CosmosDB","Adopt","Data Management","FALSE","None" 33 | "SQL Server","Adopt","Data Management","FALSE","None" 34 | "Hasuara","Adopt","Data Management","FALSE","None" 35 | "Azure Event Grid","Adopt","Data Management","FALSE","None" 36 | "Kibana","Adopt","Data Management","FALSE","None" 37 | "LogStash","Adopt","Data Management","FALSE","None" 38 | "Java 8","Adopt","Languages","FALSE","None" 39 | "Java 11","Trial","Languages","FALSE","None" 40 | "Kotlin","Adopt","Languages","FALSE","None" 41 | "C#","Adopt","Languages","FALSE","None" 42 | "C++","Hold","Languages","FALSE","None" 43 | "Python","Adopt","Languages","FALSE","None" 44 | "TypeScript","Adopt","Languages","FALSE","None" 45 | "Visual Basic","Hold","Languages","FALSE","None" 46 | "PowerShell","Adopt","Languages","FALSE","None" 47 | "JavaScript","Adopt","Languages","FALSE","None" 48 | -------------------------------------------------------------------------------- /software-engineering-policies/README.md: -------------------------------------------------------------------------------- 1 | # Software Engineering Policies 2 | 3 | The policies (and associated guidance) that should be followed during software development at the UKHO. 4 | 5 | | Area | Policy | Guidance | 6 | | :--- | :--- | :--- | 7 | | Code Copyright | [Policy](CodeCopyright/CodeCopyrightPolicy.md) | | 8 | | Code Reuse | [Policy](CodeReuse/CodeReusePolicy.md) | | 9 | | Code Review | [Policy](CodeReview/CodeReviewPolicy.md) | | 10 | | Containers | [Policy](Containers/ContainerPolicy.md) | | 11 | | Defect Management | [Policy](DefectManagement/DefectManagementPolicy.md) | | 12 | | Inclusive Language | [Policy](InclusiveLanguage/InclusiveLanguagePolicy.md) | | 13 | | 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) | 14 | | Non Functional Requirements | [Policy](NFRs/NFRPolicy.md) | | 15 | | Open Source Contribution | [Policy](OpenSourceContribution/OpenSourceContributionPolicy.md) | | 16 | | Open Source Use | [Policy](OpenSourceUse/OpenSourceUsePolicy.md) | | 17 | | Pair Programming | [Policy](PairProgramming/PairProgrammingPolicy.md) | | 18 | | Secure Development | [Policy](SecureDevelopment/SecureDevelopmentPolicy.md) | | 19 | |   Managing Security Concerns | [Policy](../security/ManagingSecurityConcerns/ManagingSecurityConcerns.md) | and [CVSS Scoring Guidance](../security/ManagingSecurityConcerns/CvssScoringMetrics.md)| 20 | | Source Control | [Policy](SourceControl/SourceControlPolicy.md) | | 21 | | System Documentation | [Policy](SystemDocumentation/SystemDocumentationPolicy.md) | | 22 | | Technical Debt | [Policy](TechnicalDebt/TechnicalDebtPolicy.md) | [Guidance](TechnicalDebt/TechnicalDebtGuidance.md) | 23 | | Third-Party Licensing | [Policy](ThirdPartyLicensing/ThirdPartyLicensingPolicy.md) | [Guidance](ThirdPartyLicensing/ThirdPartyLicensingGuidance.md) | 24 | | Unit Testing | [Policy](UnitTesting/UnitTestingPolicy.md) | [Guidance](UnitTesting/UnitTestingGuidance.md) | 25 | -------------------------------------------------------------------------------- /software-engineering-policies/Resources/baseline-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/Resources/baseline-diagram.png -------------------------------------------------------------------------------- /software-engineering-policies/Resources/control-options.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/Resources/control-options.png -------------------------------------------------------------------------------- /software-engineering-policies/SourceControl/AzDoBranchProtection.md: -------------------------------------------------------------------------------- 1 | # Branch Protection 2 | 3 | Branch protection on active repositories is important to ensure that we are doing the best we can to be clean and secure. The policies set out below are required for your main branch but options for other branches. 4 | 5 | The following options should be selected. An explanation is provided where necessary as to why this should be enabled. 6 | 7 | ## Branch Policies 8 | 9 | The following policies should be enabled against a repository to ensure that we are adhering to our source control policies and being as vigilant as possible when it comes to code reviews prior to committing our code to main. 10 | 11 | ### Require a minimum number of reviewers 12 | 13 | The team size will dictate the number of approvals required to move a pull request through the process but the ideal here should be 2. This allows for multiple views of the code from different angles to make sure what you are trying to merge fits what is required. However it is understood sometimes team sizes are not large enough for this so an absolute minimum would be 1 reviewer. 14 | 15 | #### Prohibit the most recent pusher from approving their own changes 16 | 17 | Ideally anybody who is contributing to the pull request should be getting an external review so enabling this will help us prevent developers making "small fixes" before approving and merging. 18 | 19 | #### When new changes are pushed: Reset all code reviewer votes (does not reset votes to reject or wait) 20 | 21 | Any new change indicates that the pull request needs a review from all people. However if there has been a request to reject or wait there should be a chance for these individuals to double check their concerns have been addressed before approving. 22 | 23 | ### Check for linked work items: Optional 24 | 25 | Whilst it would be ideal to have a work item attached to each pull request, there will be times where a work item cannot be attached for one reason or another. Having the warning will allow us to think about if we should have the work item when creating the pull request. 26 | 27 | ### Check for comment resolution: Required 28 | 29 | Having this set to required allows anybody who has commented to ensure that their comment has been seen and/or dealt with before a pull request has been actioned. If there are problems later in the development process then the pull request can be referenced back to and there should be no loose conversations. 30 | 31 | ### Limit merge types 32 | 33 | The preference here is to use Squash merge so that we can have a linear history and allow for multiple commits (including any errors) in a pull request without it reflecting in the main branch. However this is a team choice and the above is guidance only. 34 | 35 | ## Build Validation 36 | 37 | To ensure that what is being put into main meets expectation we should be putting build validation gates in place. Wherever there is automation to test the codebase or code changes (such as Snyk or Trivvy) then we should be adding these pipelines as a policy. This should trigger automatically whenever a change is made and should expire whenever the main branch is updated. 38 | 39 | ## Status Checks 40 | 41 | Status checks are the automated checks that run on the code to support in quality and security. Requiring these is a must but it is not enough to just turn this on, you need to be explicit in which checks you want requiring. 42 | 43 | ### Automatically Included reviewers 44 | 45 | The code owners should be the gate keepers of the repository and no code should pass this point without their knowledge or approval. It is the code owners who have the knowledge of the code and its purpose that can help guide a PR so having this is extra important. 46 | -------------------------------------------------------------------------------- /software-engineering-policies/SourceControl/GitBranchProtectionPolicy.md: -------------------------------------------------------------------------------- 1 | # Branch Protection 2 | 3 | Branch protection on active repositories is important to ensure that we are doing the best we can to be clean and secure. The policies set out below are required for your main branch but options for other branches. 4 | 5 | The following options should be selected. An explanation is provided where necessary as to why this should be enabled. 6 | 7 | ## Require a pull request before merging 8 | 9 | We should never be making any code changes to the main branch without making a pull request. This can lead to a messy history, conflicts and broken builds that can cause outages. By performing a pull request, your code can be put through quality checks, code review and even be run in an environment before being merged. 10 | 11 | ### Require approvals 12 | 13 | The team size will dictate the number of approvals required to move a pull request through the process but the ideal here should be 2. This allows for multiple views of the code from different angles to make sure what you are trying to merge fits what is required. However it is understood sometimes team sizes are not large enough for this so an absolute minimum would be 1 reviewer. 14 | 15 | ### Dismiss stale pull request approvals when new commits are pushed 16 | 17 | If a code change is made, no matter how tiny, it is best that your reviewers take another look just to be sure that everything is ok. It may seem overkill for something like a line deletion or missing semicolon however it stops code creep and ensures you are proofing your code prior to reviews in the future. 18 | 19 | ### Require reviews from Code Owners 20 | 21 | The code owners should be the gate keepers of the repository and no code should pass this point without their knowledge or approval. It is the code owners who have the knowledge of the code and its purpose that can help guide a PR so having this is extra important. 22 | 23 | 24 | ## Require status checks to pass before merging 25 | 26 | Status checks are the automated checks that run on the code to support in quality and security. Requiring these is a must but it is not enough to just turn this on, you need to be explicit in which checks you want requiring. 27 | 28 | ### Require branches to be up to date before merging 29 | 30 | It is pointless running checks and doing code reviews on code that is not inline with your main branch. It could be that your code is fine however there has been a change made that conflicts with yours that would not be found until merging. This check allows us to prevent this from happening. 31 | 32 | ### Snyk SAST status check to be required 33 | 34 | Snyk has been setup against all Repos. This means when you enable status checks to be required and you search for the status checks you want to enable, typing `snyk` into the text box provided should hopefully show `snyk/sast` and you can select it. It is important that we have this as a required check as we do not want to push insecure code into main. 35 | 36 | ## Require conversation resolution before merging 37 | 38 | If there are conversations on your pull request then it is important to know that these have been acknowledged in one way or another. Sometimes a passing comment can go unnoticed but could have an effect on something down the line. By dealing with it at the pull request we can be sure that the conversation is at least taken into consideration. 39 | 40 | ## Do not allow bypassing the above settings 41 | 42 | The point of these settings is to ensure we deliver safe and secure code where possible. By allowing anyone to bypass this would defeat the object of what we are trying to achieve. Whilst a nuisance, they provide a level of automated checks to help with the continued delivery of our code, so problems should be dealt with at the various levels and not bypassed. There will always be unique cases where this cannot be done but that must be dealt with on a case by case basis. 43 | 44 | ## Restrict who can push to matching branches 45 | 46 | As we work with 3rd parties and multiple teams, sometimes having codeowners reviewing is not enough and we need to actually restrict who is pushing to the branch. For main it should be the service owners and any other teams who are maintaining the service. 47 | -------------------------------------------------------------------------------- /software-engineering-policies/SourceControl/RepositorySetupPolicy.md: -------------------------------------------------------------------------------- 1 | # Repository Setup Policy 2 | 3 | To ensure consistency in how our repositories are setup for access and automation, the following policy has been created. This focuses on the files within the codebase, the settings within the repo and automation we expect to run. 4 | 5 | ## Codebase setup 6 | 7 | So that we can ensure that anybody interacting with the codebase knows how they can perform certain actions, the following files should be added. 8 | 9 | ### CODEOWNERS 10 | 11 | The CODEOWNERS file uses pattern matching to figure out who should be reviewing what when it comes to a pull request. For a CODEOWNERS file to be valid, the users/teams must have write permission to the repository. More information on how this can be setup and structured can be found in the [github documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) 12 | 13 | ### LICENSE 14 | 15 | This describes the license in which the codebase is under. 16 | 17 | ### CONTRIBUTING.md 18 | 19 | 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) 20 | 21 | ### SECURITY.md 22 | 23 | The security file provides a way for people interacting with the codebase to know how to raise any security issues they may have found. We have a fairly standard format for this that you can add to the file 24 | 25 | ```md 26 | # Security Notice 27 | 28 | The UK Hydrographic Office (UKHO) supplies hydrographic information to protect lives at sea. Maintaining the confidentially, integrity and availability of our services is paramount. Found a security bug? Please report it to us at UKHO-ITSO@gov.co.uk 29 | ``` 30 | 31 | ### README.md 32 | 33 | The readme is the window to the codebase. This should have a simple explanation of what the code does, how to run the code/tests and any additional information that is pertinent to the codebase. If there is extensive documentation around the codebase due to its size, breaking this up into smaller documents and having them in a docs folder is usually good practice with links out. 34 | 35 | ## Settings 36 | 37 | Setting up the repository is the key to ensuring we keep things clean and ensuring we are doing the best to implement the policies provided. 38 | 39 | ### Default Branch 40 | 41 | As stated in the Source Control policy, we should be using `main` as our default branch where possible. For new repositories this should not be a problem and should only be an issue where we may have legacy repos and pipelines. 42 | 43 | ### Features 44 | 45 | So that we are only using the features that we require of Github and avoid any confusion of where information needs to be, we should only have `Preserve this repository` enabled. In terms of the other features we use other tooling for these so by disabling them we remove possible interactions. 46 | 47 | ### Pull Requests 48 | 49 | There are multiple merging strategies for merging a pull request into a repository. 50 | 51 | - Merge commits allow us to merge all commits. 52 | - Squash and merge puts all commits into 1 and is added to the base branch. 53 | - Rebase and merge puts all commits into 1 and is rebased onto the base branch. 54 | 55 | Because of how we are setting up with our branch protection and other settings, the ideal merge strategy here would be `Squash and merge`. This gives us the room to create a pull request with multiple commits and "mistakes" but the main branch is kept clean with a single commit from the pull request. The commit message can contain a summary of everything that has been completed and the PR itself can be the history. 56 | 57 | It would be advised to disable the other 2 merge strategies so that teams are forced to use the same way of merging however this can be left up to teams to discuss and decide. 58 | 59 | Enabling `Always suggest updating pull request branches` is required as we never want to be behind the main branch when we are performing pull requests. 60 | 61 | Finally `Automatically delete head branches` is required to be enabled to support in cleaning up branches. This also supports in re-pointing branches using the deleted head branch as a base. 62 | 63 | ## Branch Protection Rules 64 | 65 | Branch protection should always be setup against your default branch. The policy for this can be found [here](/software-engineering-policies/SourceControl/BranchProtectionPolicy.md) 66 | 67 | ## Code security and analysis 68 | 69 | From a code security point of view, we already have tooling that runs against the codebase externally however to support in the maintenance of your codebase we should be enabling `Dependabot alerts`, `Dependabot security updates` and `Dependabot version updates` so that we can try and keep on top of dependency updates and vulnerability updates. 70 | -------------------------------------------------------------------------------- /software-engineering-policies/SourceControl/SourceControlPolicy.md: -------------------------------------------------------------------------------- 1 | # Source Control 2 | 3 | * All UKHO code **must** be stored in a source code repository. 4 | * Git is the preferred method of source control. 5 | * If hosted at the UKHO, these must be used on the central Azure DevOps Server system. 6 | * It is acceptable to use our official Azure DevOps instance on Azure to provide version control. 7 | * It is acceptable (and preferred) to use GitHub under our official UKHO organisation. 8 | * **No other source control systems are permitted.** 9 | * Any source code found in any other source control method must first be migrated and proven to build via a CI pipeline. 10 | * All new source will host a primary branch called _trunk_ or _main_ over _master_. 11 | 12 | ## Repository Setup 13 | 14 | Information about setting up your repository can be found [here](/software-engineering-policies/SourceControl/RepositorySetupPolicy.md) 15 | 16 | ## Access control 17 | 18 | Access to a repo should be done through a team and not through an individual as to ensure that there is never a single point of failure. Team access does not mean team ownership however. 19 | 20 | Ensure that developers with BPSS clearance are only granted read access. BPSS-cleared developers may temporarily be granted write access to a repository, provided suitable controls exist to prevent any change they make progressing to a live environment without review by a Security Cleared (SC) colleague. 21 | 22 | ## Branching 23 | 24 | As a Software Engineering collective, we endeavour to practice [github flow based development](https://docs.github.com/en/get-started/using-github/github-flow) when working within our teams and when working with 3rd parties. 25 | 26 | To be able to trace our branches back to PBI's it is preferable that we keep out branch naming consistent. The ideal would look something like 27 | 28 | `{ticket_number}/{type}-{description}` 29 | 30 | So for example if someone was working on a feature to update a button the branch name could look like 31 | 32 | `1001/feature-update-button-onclick` 33 | 34 | 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) 35 | 36 | ## Check-in comments 37 | 38 | All check-ins must be accompanied by a comment. This should be enforced by the tooling. The check-in comments should be subject to review as part of code review. 39 | 40 | The commits should be small and concise and the commit message should answer "Applying this change will...". 41 | 42 | ## Pull Requests 43 | 44 | Pull requests should follow a consistent pattern to help with reviewing. There are 3 parts to a pull request that need to be considered. 45 | 46 | ### Naming 47 | 48 | The naming for a pull request should be in a similar fashion to the branch name where the ticket, type and description is provided. For example 49 | 50 | `1001 - Feature Update button OnClick` 51 | 52 | The body of a pull request should provide the information and context a reviewer would need to proceed with looking through you code. This will include what has changed, why you changed it, any tickets relating to this change and how to test this change. If possible providing a template for this will support in ensuring that a developer will add the required information when raising a pull request. 53 | 54 | The contents of the PR should be specific to the work being described in the pull request. If there is a ticket attached then the changes should be specific to that and any deviations called out explicitly. PR sizes should not be too large as to not overwhelm your reviewers; where they do become too large a code review before hand might be of benefit. 55 | 56 | ## Verification 57 | 58 | A team's source control system must be open to inspection, including history of check-in comments. 59 | 60 | A team's branching policy and naming conventions must be available for verification. 61 | 62 | ## Build / Release Configuration 63 | 64 | Build and release pipelines should be under source control using YAML builds. 65 | 66 | Secrets should be provided by variable groups and possibly backed by a keyvault to allow for ease of maintenance. 67 | -------------------------------------------------------------------------------- /software-engineering-policies/SystemDocumentation/SystemDocumentationPolicy.md: -------------------------------------------------------------------------------- 1 | # System Documentation Policy 2 | 3 | Each system **must** have system documentation to support future maintenance of that system. 4 | 5 | It should contain the following types of information: 6 | 7 | * High-level architecture 8 | * Build process 9 | * Deployment and configuration information 10 | * Any other useful information to provide a 'jump start into the code' for a delivery team. 11 | 12 | The audience for this documentation is the delivery team. The Agile principle of "Working software over comprehensive documentation" should be followed, meaning documentation is required but should be "just enough" to capture the elements above. 13 | 14 | The documentation **must** be stored in a place relevant to the audience. 15 | 16 | Documentation **must** be treated the same as code and be subject to peer review, as per the [code review policy](../CodeReview/CodeReviewPolicy.md). 17 | 18 | It is recommended that [CommonMark](https://commonmark.org/) (a standard, unambiguous syntax specification for Markdown) is used. 19 | 20 | Each team's definition of done must include a statement on documentation. 21 | 22 | ## Other documentation 23 | 24 | DS&T does not mandate any code commenting standards. Teams may specify their own standards according to their needs, remembering: 25 | 26 | * The guidance is that code should be comprehensible without comments, and that code comments are a maintenance overhead and can indicate poor code. 27 | * Teams should consider additional user-focused documentation (e.g. Javadoc or ///) if a package is to be consumed without the source code. 28 | -------------------------------------------------------------------------------- /software-engineering-policies/TechnicalDebt/Example_TD_V4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/TechnicalDebt/Example_TD_V4.png -------------------------------------------------------------------------------- /software-engineering-policies/TechnicalDebt/Porfolio_TD_V1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/TechnicalDebt/Porfolio_TD_V1.png -------------------------------------------------------------------------------- /software-engineering-policies/TechnicalDebt/TechnicalDebtMonitoring.md: -------------------------------------------------------------------------------- 1 | # Technical Debt Monitoring 2 | 3 | ## Pre-requisites 4 | 5 | - Each project will need a `Technical debt` work item type in their process. 6 | - This has to be added by a process editor. 7 | - if you are using the default **DGf** template then the project will have a Technical debt type already. 8 | - Each project will need a "Technical Debt" dash board. 9 | - An aggregation of all the "Technical Debt" will be visible on a central dashboard. 10 | 11 | ![Dashboard Technical Debt](./dashboard_TD_V1.png) 12 | 13 | ## Work item fields 14 | 15 | * A **Technical debt** work item type **MUST** be created in target project. 16 | * Add new Details section with the following fields (use existing field, do not create a new field): 17 | * Primary Product or Service 18 | * there may be several interconnecting products but which is the main one, if needed, create a separate TD item for each product if they would be addressed separately. 19 | * Technical priority 20 | * TD1 - High business/technical value, high risk debt that needs to be paid off ASAP (a Security tag should automatically be considered for a TD1 prioritisation). 21 | * TD2 - High business/technical value (cost reduction, blocker removing, maintainability improvement), lower risk, a change that should be worked on when time/opportunity permits and is not something that can be accepted or supported long term. 22 | * TD3 - Tech debt that has been accepted as a risk but through paying off would add value through improving usability, maintainability, reliability or performance. 23 | * TD4 - Accepted risk from the business, safe to leave until service reaches end of life. Worth tracking in case developers are working in the area and can complete as quick wins. 24 | * Technical debt type 25 | * Architectural – Tightly coupled systems (lots of criss-crossed dependencies), * restrictive to extension or automation 26 | * Code – Low quality code or ineffective patterns 27 | * Knowledge – lack of documentation or inaccessible documentation 28 | * Automation – Lack of automated tasks forcing manual intervention (Testing, deployments, * backup/restore) 29 | * Testing – Unknown or unrecorded test scenarios, lack of test coverage 30 | * Maintenance – Out-of-support products, usually leading to security vulnerabilities 31 | * Process - inefficient or wasteful process steps, this could be related to practice or * tooling 32 | * Security - Known and exploitable vulnerabilities 33 | * Technical debt impact 34 | * Increased time to deliver 35 | * Unplanned work 36 | * Inaccurate planning 37 | * Disengaged Development teams 38 | * Longer times to recover 39 | * Instability 40 | * Security Concerns 41 | * Add a new section called Status 42 | * Add field for Scheduled Release 43 | 44 | ## Using `Technical debt` work items 45 | 46 | Once created the work item can be added to the team boards as part of the process backlog level, to allow tracking at the "Requirements backlog" level or as a separate backlog level, similar to features and epics. 47 | 48 | The Technical debt portfolio backlog will need to be added to each team view as needed. 49 | 50 | ![Portfolio Technical Debt](./Porfolio_TD_V1.png) 51 | -------------------------------------------------------------------------------- /software-engineering-policies/TechnicalDebt/dashboard_TD_V1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/UKHO/docs/7116076e2887e584c9440e8a942240d7de0cc071/software-engineering-policies/TechnicalDebt/dashboard_TD_V1.png -------------------------------------------------------------------------------- /software-engineering-policies/TechnologyGovernance/TechnologyGovernance.md: -------------------------------------------------------------------------------- 1 | # Technology Governance 2 | 3 | This page describes how UKHO engineering teams govern change in the technology we use. 4 | 5 | ## Aims 6 | 7 | The aims of our tech governance process are to balance: 8 | 9 | * Innovation 10 | * Developer motivation 11 | 12 | VERSUS 13 | 14 | * Growing our expertise 15 | * Sharing skills 16 | * Re-using code 17 | * Mobility 18 | 19 | Further goals are to: 20 | 21 | * Keep bureaucracy low 22 | * Not undermine the role of solution architects 23 | * Keep decision-making with experts 24 | 25 | ## Use of Tech Radars 26 | 27 | Each team must maintain a tech radar on our standard tool (). The Lead Developer is accountable for making sure that this kept up to date. 28 | 29 | When a change is made to a radar, the Lead Developer must do the following: 30 | 31 | * When a team begins to investigate or trial a new technology, they must add it to their team's tech radar as *"Monitor"* immediately, and they must inform the next Leads' meeting to get feedback. If the team subsequently decides not to continue to use the technology, they should remove it from their radar with some details as to why they chose not to continue with it. 32 | * If they wish to adopt a technology, such as moving that technology into production or using the technology as part of their day-to-day team processes, they must ask permission from the Lead Developers' meeting and following approval, the technology must be moved into the *"Buy"* ring of the radar. The decision is made by Lead Developers by a simple majority. 33 | * If they need to start using a technology urgently, they may continue at risk until the next Leads' meeting. 34 | 35 | ## Solution Architecture and Architects 36 | 37 | This process only covers technology that is not the responsibility of Solution Architects (SAs). SAs will generally be concerned with building blocks (e.g. databases, network architecture, message transport, execution environments etc.), where Lead Developers will be concerned with lower level components, frameworks and development tools (e.g. programming languages, testing frameworks, UI frameworks, build tools). 38 | 39 | Sometimes responsibility is not clear-cut, so it is vital that Lead Developers maintain a dialogue with their SA about technology choice. 40 | 41 | ## Scope 42 | 43 | This technology governance process applies only to Software Engineering Teams. It does not apply to Data Engineering Teams. 44 | -------------------------------------------------------------------------------- /software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingGuidance.md: -------------------------------------------------------------------------------- 1 | # Licensing of Third Party Libraries Guidance 2 | 3 | ​​​​A great resource for finding clear and concise information on a very large range of licences is [tl;drLegal](https://tldrlegal.com/). 4 | 5 | This site provides a useful comparison of licences by boiling each licence down into three columns: can, cannot and must. 6 | 7 | For a licence to be suitable for use at the UKHO, on the td;lrLegal page for the licence the: 8 | 9 | Can column must contain: 10 | 11 | * Private use 12 | * Commercial use 13 | 14 | Cannot column must not contain: 15 | 16 | * Sublicence 17 | 18 | Must column must not contain: 19 | 20 | * Disclose Source​ 21 | -------------------------------------------------------------------------------- /software-engineering-policies/ThirdPartyLicensing/ThirdPartyLicensingPolicy.md: -------------------------------------------------------------------------------- 1 | # Licensing of Third Party Libraries Policy 2 | 3 | ## Background 4 | 5 | All UKHO software should make use of third party components, in preference to re-writing, wherever practical, but with special consideration with respect to the licence under which a component is released. The reason being that use of a component can legally impose conditions according to its the terms of its licence. For example: using a component released under the GLP-3 licence requires (amongst other things) that code linked to the component must be disclosed under a GPL 3.0 compatible licence.​ 6 | 7 | ## Guide 8 | 9 | All third party components used in UKHO software **must** have been released under an appropriate licence included in the following list of approved licences. 10 | 11 | All changes to third-party components **must** be reviewed by the team's Lead Engineer. 12 | 13 | If a third party component is proposed for use that has not been released under an approved licence and the licence appears to be reasonable, then the team's Lead engineer should propose that the licence be added to the list at the Lead engineer's meeting. If further clarity is needed then TPE management​ and the Legal department will be consulted. 14 | 15 | ## Allowlist of approved licenses​ 16 | 17 | - MIT License (Expat) 18 | - Apache License 2.0 (Apache-2.0) 19 | - BSD 2-Clause License (FreeBSD/Simplified) 20 | - BSD 3-Clause License (Revised) 21 | - ISC License 22 | - Boost Software License 1.0 (BSL-1.0) 23 | - Free Public License 1.0.0 24 | - University of Illinois - NCSA Open Source License (NCSA) 25 | - X11 License 26 | - The JSON License 27 | - BSD 0-Clause License (0BSD) 28 | - Very Simple Public License (VSPL) 29 | - The Don't Ask Me About It License 30 | - Universal Permissive License 1.0 (UPL-1.0) 31 | - Copyfree Open Innovation License 0.3 (COIL-0.3)​ 32 | - Microsoft Public License (Ms-PL)​ 33 | - Microsoft Shared Source Community License (MS-CL)​​ 34 | 35 | ## Verify 36 | 37 | Verification will be automated. Contact the DDC team to find out how this works. 38 | 39 | -------------------------------------------------------------------------------- /software-engineering-policies/UnitTesting/UnitTestingPolicy.md: -------------------------------------------------------------------------------- 1 | # Unit Testing Policy 2 | 3 | ## Guide 4 | 5 | All new non-trivial code **must** be covered with unit tests. Ultimately, the definition of 'non-trivial' is up to the team's Lead Engineer. 6 | 7 | Areas of code may be excluded from this rule (e.g. boiler-pate, or generated code) by the Lead Engineer. 8 | 9 | Where legacy code or some other factor makes unit testing difficult, a pragmatic approach may be taken. The Lead Engineer engineer is accountable for an effective decision-making process being used for what may be excluded from unit testing. 10 | 11 | Unit tests **must** be run as part of a CI process. 12 | 13 | A clear statement on unit testing must be part of written definition of done. 14 | 15 | Unit tests should be checked in at the same time as subject code and **must** be subject to code review. 16 | 17 | Teams should report on test coverage. Good coverage levels should be maintained and reductions in coverage justified. 18 | 19 | Mutation testing has been shown to be useful in assessing the quality of unit tests, and could be used by teams. 20 | 21 | ## Verify 22 | 23 | The following artefacts are subject to verification: 24 | 25 | - Team 'definition of done' documents 26 | - Unit test coverage reports 27 | - Change sets checked into source control, including unit tests 28 | -------------------------------------------------------------------------------- /software-engineering-policies/development-principles.md: -------------------------------------------------------------------------------- 1 | # Development Principles 2 | 3 | These are our overarching principles for development: 4 | 5 | 1. We understand the value of our code. 6 | 1. We understand the impact of failure and build appropriately. 7 | 1. We write high quality code. 8 | 1. We seek confidence in release. 9 | 1. We seek reuse of our code. 10 | 1. We take a full lifecycle view. 11 | 1. We keep our designs simple. 12 | 1. We seek opposing views. 13 | 1. We look externally when deciding about technology. 14 | 15 | ## We understand the value of our code 16 | 17 | We understand the value of what we are delivering, using this to make decisions about how we work. 18 | 19 | ## We understand the impact of failure and build appropriately 20 | 21 | We build in quality and security controls appropriate to the impact of failure of the systems. 22 | 23 | ## We write high quality code 24 | 25 | We write code covered by automated tests and reviewed by colleagues. 26 | 27 | ## We seek confidence in release 28 | 29 | We favour options that will increase our confidence in releasing products and services. 30 | 31 | ## We seek reuse of our code 32 | 33 | We don’t create the same thing twice. We look for opportunities to collaborate and re-use existing implementations. 34 | 35 | ## We take a full lifecycle view 36 | 37 | We write systems that are robust and easy to support, with appropriate monitoring and instrumentation. 38 | 39 | ## We keep our designs simple 40 | 41 | We favour designs that are easy to understand and communicate. 42 | 43 | ## We seek opposing views 44 | 45 | We strive for teams that understand and create psychologically safe environments, openly seeking views that challenge our ideas and assumptions. 46 | 47 | ## We look externally when deciding about technology 48 | 49 | We look for best practice and innovative solutions elsewhere in government and industry, and reuse them in the UKHO. 50 | -------------------------------------------------------------------------------- /software-engineering-policies/engineering-team.md: -------------------------------------------------------------------------------- 1 | # Software Engineering at the UKHO 2 | 3 | We have eight software engineering teams that develop and support software using the .Net and Java stacks. 4 | 5 | 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. 6 | 7 | ## How we work 8 | 9 | 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, product owner and a delivery manager - as well as access to infrastructure specialists, UX experts and analysts. 10 | 11 | Quality is paramount. You and your team will be supported to do good work. Most code is done in pairs or larger groups to ensure quality and spread knowledge. Everyone reviews code and everyone welcomes feedback. 12 | 13 | We strive to automate as much as possible; testing, builds, deployments use the latest tools available. 14 | 15 | ## Our community 16 | 17 | Within this practice, we encourage the formation of other communities to support our interests and our work. 18 | 19 | The community of Lead Developers provides technical leadership for the department, 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. 20 | 21 | Our Security Champion community is made up of people interested in application security, and coaches teams to create safer software, as well as increasing their own skills and qualifications. 22 | 23 | We also have many other communities of interest covering such things as Accessibility, Testing, UX, Azure, AWS and .Net. 24 | 25 | ## Balance 26 | 27 | We offer a great work / life balance. Peoples’ start and end times are built around their own preferences and 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 reasonable accommodations to help people meet their needs. 28 | -------------------------------------------------------------------------------- /software-engineering/roles/principal-developer.md: -------------------------------------------------------------------------------- 1 | # Principal Developer 2 | 3 | | Area | Tasks | Example stories | 4 | | --- | --- | --- | 5 | | Leading delivery of large programmes of work | Co-ordinating work across multiple teams | ADDS | 6 | | | | Data Hub | 7 | | | | Sailing Directions | 8 | | | | Dashboard Visibility Project | 9 | | | Feedback to Senior Managers | Whilst individual delivery teams are responsible for their own progress feedback, the Principal Dev will be frequently reporting on overall progress, particularly from the technical perspective. | | 10 | | | Tech/non-tech translations at high level | | 11 | | Technical Oversight | Technology Sharing | By working closely with multiple teams, the Principals can spot where a solution from one team can help another team. | 12 | | | | Identify and support shared libraries. | 13 | | | Ensuring whole system security | With large programmes of work, the Principal Developer is responsible for ensuring a consistent security standard across the whole system, including ensuring that the security solutions in each component is compatible with the other components in the system so that we don't need any compromise in security to get the components to talk to each other. | 14 | | | Ensuring whole system supportability | Promoting best practice in terms of SRE. Considering end-to-end software lifecycle (from requirements capture to software delivery, support and eventual sunset). | 15 | | | Support Enterprise Capabilities as SME | Logging and Observability (Elastic) | 16 | | | | Cloud Strategy | 17 | | | | SAST implementation (Snyk) | 18 | | | | Containerisation (Kubernetes Platform) | 19 | | | Advising on changes to older systems | The Principal Developers have knowledge of a lot of the existing/older systems within the UKHO and will of often be called to advise on either fixing problems with existing systems, or for enhancement of existing systems | 20 | | Technical Product Ownership | Work with architects to define target and transitional solution architectures | Data Hub/UDU, DashboardAvailability | 21 | | | Own product backlog, create and detail PBI’s | Data Hub, DashboardAvailability | 22 | | | Work with delivery managers to plan and align roadmaps | Data Hub/UDU, DashboardAvailability | 23 | | | Contribute to business cases, and work with Service Owners to define a SoW for a product | Data Hub, DashboardAvailability | 24 | | | Work with ITSO to ensure product meets security standards via SbD compliance | Data Hub | 25 | | Strategic Planning for the Development Practice | Strategic selection of Technologies | Assessing new technologies for their appropriateness for UKHO Delivery Teams | 26 | | | Implement PoC’s and demonstrate technologies and tooling | Argo Rollouts | 27 | | | Contribute and oversee development of cloud and container policies | Container, Cloud Development | 28 | | | Define required skills and training for technical teams| | 29 | | | What is the long term? Where do we want to be? How do we want delivery teams to deliver software eng in 5 years' time: Technology, People, Skills | 30 | | Bridge between teams & Practices | Linking Development and Architecture | Attend APF as Development Practice representative | 31 | | | Links with Testing Practice | Working closely with the test leads to help ensure teams deliver using the most appropriate testing practices | 32 | | Consultancy | | Providing consultancy across the teams and the wider business (TBC) | 33 | | 3rd Party Technical Contact | Supplier Management | Working with the ADDS Project Managers to define work packages for 3rd party delivery | 34 | | || Working closely with the 3rd party delivery team to ensure that the delivery remains on track and provides the technical functionality to fit into the UKHO Systems | 35 | | | Helping suppliers integrate into UKHO Systems | | 36 | | Recruitment | Consulted on recruitment within software engineering | Although not responsible for recruitment, principals can be consulted to help where necessary, for example by helping to define a role | 37 | -------------------------------------------------------------------------------- /using-github/creating-a-contributing-file.md: -------------------------------------------------------------------------------- 1 | # Creating a CONTRIBUTING.md file 2 | 3 | ## Overview 4 | 5 | The CONTRIBUTING.md is the file that users will normally read before contributing to a project and it must provide them with the information needed to contribute to the project in a style which the owner wants. The CONTRIBUTING.md allows the owner to specify the standards and processes they want contributors to use thus setting the rules for everyone, including the rules for how the owner treats contributors. The CONTRIBUTING.md is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) and placed in the root directory of the repository. 6 | 7 | If a repo does not have a CONTRIBUTING.md then we do not class it as "open" and the owner may not want external contributions. 8 | 9 | ### Must Have 10 | 11 | * Repo owner (Can be team or individual) 12 | * Contact details for owner (Email) 13 | * A welcome/intro paragraph. 14 | 15 | ### May Have 16 | 17 | * Link to documentation 18 | * Link to issue tracker 19 | * Instructions on how to run tests locally 20 | * Instructions on how to develop code locally 21 | * Pull Request process 22 | * Style guide 23 | * Where a user can find help 24 | * Security issue reporting 25 | * How to report bugs 26 | * How to request a feature 27 | * Code of Conduct 28 | * The recognition model(how people are thanked) 29 | * Philosophy of the project 30 | * Versioning process 31 | * Commit message guidance 32 | * Definition of done 33 | * Roadmap 34 | * Branching conventions 35 | * Anything else that seems relevant 36 | 37 | ### Resources 38 | 39 | * [Mozilla tutorial](https://mozillascience.github.io/working-open-workshop/contributing/) - Good guide on creating/thinking about writing a CONTRIBUTING.MD. 40 | * [Template contributing.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) - Example base template of a CONTRIBUTING.MD. 41 | * [Understanding the InnerSource Checklist](http://paypal.github.io/InnerSourceCommons/assets/files/InnerSourceChecklist.pdf) - pg. 25 - Creating good house rules for guests: Writing contributing agreements. 42 | 43 | ### Examples 44 | 45 | * [Atom](https://github.com/atom/atom/blob/master/CONTRIBUTING.md) 46 | * [OpenGovernment](https://github.com/opengovernment/opengovernment/blob/master/CONTRIBUTING.md) 47 | * [Rails](https://github.com/rails/rails/blob/master/CONTRIBUTING.md) 48 | * [GitLab](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md) 49 | -------------------------------------------------------------------------------- /using-github/creating-a-readme-file.md: -------------------------------------------------------------------------------- 1 | # Creating a README.md file 2 | 3 | ## Overview 4 | 5 | The README.md is the first file people look in when evaluating whether to use or contribute to a repo, so when writing them ensure the information is relevant to someone who doesn't know your repo and doesn't care about it. You need to provide just enough information for someone to understand the goals of the repo, download it and get started using it. The README.md is written in [Markdown](https://en.wikipedia.org/wiki/Markdown) and placed in the root directory of the repository. 6 | 7 | It is not the place for detailed documentation, keep that elsewhere and include links to it. The README.md should also feel familiar, you have probably looked at hundreds of README.md's over the year without realising, try to keep yours in the same style so it feels natural to the reader. 8 | 9 | ### Must Have 10 | 11 | * Title of project 12 | * Introductory paragraph 13 | * Caveats/Limitations 14 | 15 | ### Should Have 16 | 17 | * Demo/Usage (Only very basic) 18 | * Installation 19 | * Description of features (this can be rolled into the introductory paragraph) 20 | 21 | ### May Have 22 | 23 | * Build badges 24 | * Single sentence summary 25 | * Pictures/GIFs 26 | * How to run the tests 27 | * How to run the application 28 | * Link to the license 29 | * Example HTTP requests/responses (if that kind of repo) 30 | * Version/Changelog 31 | * Table of Contents 32 | * Link to documentation 33 | * Background context, why have you written this 34 | * Team members/contributors. 35 | * Anything else that seems relevant 36 | 37 | ### Resources 38 | 39 | * [Awesome Readme](https://github.com/matiassingers/awesome-readme) - An "awesome-list" for readme. 40 | * [Art Of Readme](https://github.com/noffle/art-of-readme) - Aimed at Node projects but lots of relevant information and philosophy of writing good readme's. 41 | * [GOV.UK Readme Guidance incl Template](https://docs.publishing.service.gov.uk/manual/readmes.html) - A bit heavyweight compared to other advice but relevant and useful. 42 | * [Template](https://github.com/RichardLitt/standard-readme). 43 | 44 | ## Examples 45 | 46 | * [Electron-Markdownify](https://github.com/amitmerchant1990/electron-markdownify). 47 | * [HTTPie](https://github.com/jakubroztocil/httpie) - Bit long, all documentation is in it. 48 | * [NSGIF](https://github.com/NSRare/NSGIF). 49 | * [Gaze](https://github.com/shama/gaze). 50 | -------------------------------------------------------------------------------- /using-github/migrating-to-github.md: -------------------------------------------------------------------------------- 1 | # Migrating an existing project to GitHub 2 | 3 | ## Remove sensitive data 4 | 5 | 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. 6 | 7 | ## Remove lines from commit messages 8 | 9 | Gerrit leaves a `Commit-Id` line in every commit message made. To remove these, the `--msg-filter` can be used as follows: 10 | 11 | ```bash 12 | git filter-branch -f --msg-filter 'sed "/Change-Id/ d"' -- --all 13 | ``` 14 | 15 | Substitute `Change-Id` for any string to match an entire line and delete from all commit message in the branch. 16 | 17 | ## Remove directories/files from branch trees 18 | 19 | To remove directories from the entire history of a branch, use the `--tree-filter` as follows: 20 | 21 | ```bash 22 | git filter-branch --tree-filter "rm -rf dev" --prune-empty HEAD 23 | ``` 24 | -------------------------------------------------------------------------------- /using-github/pull-request-details.md: -------------------------------------------------------------------------------- 1 | # Making a Pull Request 2 | 3 | This is a suggested process, individual repositories will want pull requests to be constructed differently. Check the repo's "CONTRIBUTING.md" for specific guidelines and ask if you are unsure! 4 | 5 | ## Suggested Pull Request Process 6 | 7 | * Clone repository locally. 8 | * Create a new branch off the master branch. 9 | * Make changes with clear commits following [good commit guidelines](https://chris.beams.io/posts/git-commit/). 10 | * Pull down any changes that might have happened whilst you were making your changes and merge them in locally. 11 | * Push the branch you made your changes on up to the server. 12 | * Create a pull request from the branch into master. 13 | * A build will be triggered and go green before a PR is accepted. 14 | * The changes will be reviewed by the owners of the repo and can suggest changes. 15 | * Make suggested changes and push them up to the branch again. 16 | * Owner of the repository will accept and merge your changes into master. 17 | 18 | NOTE: If you are making a large feature/architectural changes, open an issue first and discuss it with the owner as they might have additional insights or don't think it is appropriate for the repo. 19 | 20 | ## Resources 21 | 22 | * [Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962) 23 | * [How To Write The Perfect Pull Request](https://github.com/blog/1943-how-to-write-the-perfect-pull-request) 24 | * [Making A Pull Request](https://www.atlassian.com/git/tutorials/making-a-pull-request) 25 | * [GitHub Flow](https://guides.github.com/introduction/flow/) - Really high level 26 | * [Atomic Commits](https://www.freshconsulting.com/atomic-commits/) 27 | -------------------------------------------------------------------------------- /using-github/readme.md: -------------------------------------------------------------------------------- 1 | # Our guidance for using GitHub 2 | 3 | ## Background 4 | 5 | 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. 6 | 7 | ## Overview 8 | 9 | All open repos must contain the following: 10 | 11 | * **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). 12 | 13 | * **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. 14 | * **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). 15 | 16 | * **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! 17 | 18 | Above is the minimum for what an open repo must contain, other useful things a repo may contain: 19 | 20 | * Code of Conduct 21 | * [Code of Conduct from contributor covenant](https://www.contributor-covenant.org/). 22 | 23 | * Changelog 24 | * [Keep a changelog](http://keepachangelog.com/en/0.3.0/). 25 | 26 | * TDL (Technical decision log) 27 | * [Documenting Architecture Decisions](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). 28 | * [Architecture Decision Records In action presentation](https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf). 29 | 30 | * Scripts 31 | * ```script/bootstrap``` - Configure the machine ready to develop for this repo (pull down and configure dependencies etc.) 32 | * ```script/dev``` - Start any background processes/servers needed during development 33 | * ```script/test``` - Run all the tests for this repo. 34 | 35 | ## Code Contribution Process 36 | 37 | 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). 38 | 39 | ## Terminology 40 | 41 | ```Contributing``` - This is more than just adding code, this also includes creating issues/bug reports, asking questions, improving documentation. 42 | 43 | ```Contributor``` - This refers to anyone who has added to this project, including filing issues. 44 | 45 | ```Repo``` - A git repository and the associated Github/lab with it. 46 | 47 | ```Pull Request``` - How a contributor asks the owner of a repository to accept their contribution. The owner "pulls" the contribution into the main repository. 48 | 49 | ## Inspiration 50 | 51 | [Alpha Gov - Open Standards](https://github.com/alphagov/open-standards) 52 | --------------------------------------------------------------------------------