Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated techical documentation #328

Merged
merged 5 commits into from
Oct 31, 2023
Merged

Updated techical documentation #328

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a68e6bd
Updated documentation to:
keithkennedyHO Oct 30, 2023
06daf4e
Minor text correction
keithkennedyHO Oct 30, 2023
b22c342
replaced out of sequence section on reporting security vulnerability
edhamiltonHO Oct 30, 2023
b47d8bf
Update technical-docs/architecture-decision-records/technical-decisio…
keithkennedyHO Oct 30, 2023
5b850de
Clarified language on move to home office platform
edhamiltonHO Oct 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 4 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ We will now look at the process we expect contributors to take when suggesting f
- propose a new principle
- propose a new standard
- review any existing content
- report a security vulnerability

### Solve an issue

Expand Down Expand Up @@ -57,12 +58,6 @@ Make sure you pull your fork and switch to your new branch to do these changes.

Don't forget to commit and push your changes to your forked repo ready for the contribution!

## Security vulnerability

### Report a security vulnerability

You can report a security vulnerability to the Home Office Engineering Guidance and Standards team using the [repository's security advisory page](https://github.com/UKHomeOffice/engineering-guidance-and-standards/security/advisories/new).

## Pull Requests

When you're finished with your changes you should create a pull request, commonly known as a PR.
Expand All @@ -75,7 +70,7 @@ When creating a PR, use the appropriate template checklists for code and content

### Who can merge your PR

Any 2 of the maintainers on this repo are needed to accept your change.
Any 2 of the maintainers on this repo are needed to review and accept your change and at least 1 reviewer must be a [code owner](https://github.com/UKHomeOffice/engineering-guidance-and-standards/blob/main/CODEOWNERS).

## Your PR is merged!

Expand Down Expand Up @@ -106,13 +101,13 @@ The following actions are performed for each PR:

PRs must only be approved after they pass the above checks.

We are deploying the site to [GitHub pages](https://pages.github.com/).
We are deploying the site to a Docker container.

## Branching

### Branching strategy

We are using a simple trunk based strategy. There is only a single environment being used, as GitHub pages does not support more than 1 active site.
We are using a simple trunk based strategy.

### Review

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This is the home of engineering guidance and standards for the Home Office. Learn more about this project on the [about page](https://engineering.homeoffice.gov.uk/about/).

It is built using Markdown, GOV.UK templates, HO styles, the x-gov Eleventy Plugin, GitHub Actions and GitHub pages.
It is built using Markdown, GOV.UK templates, HO styles, the [x-gov Eleventy Plugin](https://x-govuk.github.io/govuk-eleventy-plugin/) and GitHub Actions.

## Requirements

Expand Down
4 changes: 3 additions & 1 deletion SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

## Report a security vulnerability

You can report a vulnerability to the Home Office Engineering Guidance and Standards team through the [repository's security advisory page](https://github.com/UKHomeOffice/engineering-guidance-and-standards/security/advisories/new).
You can report a vulnerability to the Home Office Engineering Guidance and Standards team using the following methods:
- Raise an issue on the [repository's security advisory page](https://github.com/UKHomeOffice/engineering-guidance-and-standards/security/advisories/new)
- Email [[email protected]](mailto:[email protected])

Please enter as much information as possible in your report, this will help us better triage the vulnerability.

Expand Down
12 changes: 7 additions & 5 deletions technical-docs/architecture-decision-records/technical-decision-log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# Technical Decision Log

| Issue# | Description | Notes | Decision | Decision Date | Further Information |
|--------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|---------------------|
| N/A (Initial repository creation) | Choice of static site generator | Considered use of the [GDS Tech Docs Template](https://github.com/alphagov/tech-docs-template) (Ruby based) and the [x-Gov Eleventy Plugin](https://github.com/x-govuk/govuk-eleventy-plugin) (Node.js based). Both options easily configurable and restyled, Eleventy plugin receives slightly more regular and recent maintenance. | Use the x-Gov Eleventy Plugin for creation of this site, due to better inhouse familiarity with Node.js and better record of plugin maintenance. | 2022-05-17 | None |
| 66 | Add secret scanning to GitHub repository | GitHub provides secret scanning functionality. Users will receive alerts on GitHub for detected secrets, keys, or other tokens. Push protection can be enabled which will block commits that contain [supported secrets](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets). These settings can be found within the settings section "Code security and analysis". | Enable "Secret scanning" with "Push protection" within repository settings. Organisation administrators, repository administrators and teams with the security manager role will receive alerts when scan detects a secret. | 2023-06-01 | None |
| 65 | Add dependency vulnerability scanning using Dependabot to GitHub repository | GitHib provides dependency vulnerability scanning functionality. [Dependabot can be configured to automatically raise pull requests](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). | Dependabot configured to scan npm dependencies daily and github-actions dependencies weekly. These differ due to anticipated update cadence. | 2023-06-02 | None |
| 130 | Ignore phase banner being outside landmark regions | Those elements being outside a landmark region is a moderate level failure. It is not considered to be a high priority issue by the Gov.uk design system team. See [Github issue where phase banner and landmarks is discussed](https://github.com/alphagov/govuk-frontend/issues/1604). We will revisit this decision as part of a planned review of the site design as a whole. | Axe-core has been configured to ignore elements with a `data-axe-exclude` attribute. This has been added to the phase banner and breadcrumbs. | 2023-06-16 | None |
|--------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------------|
| N/A (Initial repository creation) | Choice of static site generator | Considered use of the [GDS Tech Docs Template](https://github.com/alphagov/tech-docs-template) (Ruby based) and the [x-Gov Eleventy Plugin](https://github.com/x-govuk/govuk-eleventy-plugin) (Node.js based). Both options easily configurable and restyled, Eleventy plugin receives slightly more regular and recent maintenance. | Use the x-Gov Eleventy Plugin for creation of this site, due to better inhouse familiarity with Node.js and better record of plugin maintenance. | 2022-05-17 | None |
| 66 | Add secret scanning to GitHub repository | GitHub provides secret scanning functionality. Users will receive alerts on GitHub for detected secrets, keys, or other tokens. Push protection can be enabled which will block commits that contain [supported secrets](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-patterns#supported-secrets). These settings can be found within the settings section "Code security and analysis". | Enable "Secret scanning" with "Push protection" within repository settings. Organisation administrators, repository administrators and teams with the security manager role will receive alerts when scan detects a secret. | 2023-06-01 | None |
| 65 | Add dependency vulnerability scanning using Dependabot to GitHub repository | GitHib provides dependency vulnerability scanning functionality. [Dependabot can be configured to automatically raise pull requests](https://docs.github.com/en/enterprise-cloud@latest/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates). | Dependabot configured to scan npm dependencies daily and github-actions dependencies weekly. These differ due to anticipated update cadence. | 2023-06-02 | None |
| 130 | Ignore phase banner being outside landmark regions | Those elements being outside a landmark region is a moderate level failure. It is not considered to be a high priority issue by the Gov.uk design system team. See [Github issue where phase banner and landmarks is discussed](https://github.com/alphagov/govuk-frontend/issues/1604). We will revisit this decision as part of a planned review of the site design as a whole. | Axe-core has been configured to ignore elements with a `data-axe-exclude` attribute. This has been added to the phase banner and breadcrumbs. | 2023-06-16 | None |
| 72 | Switch to hosting the site on a Home Office platform from GitHub Pages | In order to host the site under a Home Office domain (https://engineering.homeoffice.gov.uk), we are required to host the site on the Home Office application container platform. | Deployment actions updated to deploy to Home Office platform. | 2023-06-13 | None |
| 72 | Migration of repository to [UK Home Office](https://github.com/UKHomeOffice) organisation from [HO CTO](https://github.com/HO-CTO/) | Migration of repository was required to allow hosting of application on the Home Office platform (see previous decision log item). | Migration of repository to [UK Home Office](https://github.com/UKHomeOffice/engineering-guidance-and-standards). The [previous repository location](https://github.com/HO-CTO/engineering-guidance-and-standards) has been updated to provide a redirection to the new location. | 2023-06-13 | None |