ministryofjustice / technical-guidance

How we build and operate products at the Ministry of Justice. • This repository is defined and managed in Terraform

Technical guidance

How we build and operate products at the Ministry of Justice. This repo is inspired by, and borrows from, GDS's technical guidance site.

It's built using the gov.uk tech-docs-template, and hosted using GitHub Pages.

Getting started

To preview the site locally, we need to use the terminal, and run:

make preview

This will create a local web server, at http://localhost:4567 This is only accessible on our own computer, and won't be accessible to anyone else.

To test the URLs:

make check

Making changes

To make changes, edit the appropriate Markdown files in/below the source/documentation directory.

Make sure to make changes in a branch, and issue a pull request when you want them to be reviewed and published.

Publishing changes

Any changes merged into the main branch will be published automatically.

Every change should be reviewed in a pull request, no matter how minor, and we've enabled branch protection to enforce this.

technical-guidance's Issues

Update out of hours support guidance to advise on what level of seniority staff on call should be

As @Tocacar says in #55:

Also, perhaps we need to include a statement on which level of staff is acceptable to be on call, which is possibly where things become tricky. My feeling is that senior and mid level developers can be on call, however, probably not two mid levels. It's probably infeasible to require a senior to be on call. I'm interested to hear thoughts here. I feel a junior can a secondary and should experience on call, but possibly not if a mid-level is primary? I suppose decisions will need to be made pragmatically on a team by team basis, but some guidance will probably be useful.

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/standards/naming-domains.html.md.erb

• [503] https://gov.wales/register-and-manage-domains-llywcymru-and-govwales | Failed: Network error: Service Unavailable
  Full Github Actions output

User access removed, access is now via a team

Hi there

The user benmillar-cgi either had direct member access to the repository or had direct member access and access via a team.

Access is now only via a team.

If the user was already in a team, then their direct access to the repository has been removed.

If the user was not in a team, then the user will have been added to an automated generated team named repository-name-<read|write|maintain|admin>-team and their direct access to the repository has been removed.

The list of Org teams can be found at https://github.com/orgs/ministryofjustice/teams or https://github.com/orgs/moj-analytical-services/teams.

The user will have the same level of access to the repository via the team.

The first user added to a team is made a team maintainer, this enables that user to manage the users within the team.

Users with admin access are added to the admin team as a team maintainer.

If you have any questions, please contact us in #ask-operations-engineering on Slack.

This issue can be closed.

Guidance for external pull requests

We have an open repo within the MOJ Org on github, recently we had a PR from a dev based in Brazil.

It is a tiny PR adding a test and removing a TODO to add some tests later.

A month previously I would have thanked the developer and merged the PR but this was opened shortly after a vuln disclosure around github actions potentially leaking secrets so I was looking for some guidance

Steps:

• Add CONTRIBUTORS.md file to template.

Link Checker Report

Summary

Status	Count
🔍 Total	125
✅ Successful	116
⏳ Timeouts	1
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	0

Errors per input

Errors in README.md

• [TIMEOUT] https://img.shields.io/endpoint?labelColor=231f20&color=005ea5&style=for-the-badge&label=MoJ%20Compliant&url=https%3A%2F%2Foperations-engineering-reports.cloud-platform.service.justice.gov.uk%2Fapi%2Fv1%2Fcompliant_public_repositories%2Fendpoint%2Ftechnical-guidance&logo=data:image/png;base64,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 | Timeout
  Full Github Actions output

Check spelling in pull requests

We should be able to use danger-prose to do spell-checking on PRs.

Link Checker Report

Summary

Status	Count
🔍 Total	125
✅ Successful	117
⏳ Timeouts	1
🔀 Redirected	0
👻 Excluded	7
❓ Unknown	0
🚫 Errors	0

Errors per input

Errors in README.md

• [TIMEOUT] https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-github-repositories.html#technical-guidance | Timeout
  Full Github Actions output

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/standards/how-to-get-a-domain-name.html.md.erb

• [404] https://ministryofjustice.github.io/operations-engineering/documentation/services/domain-management.html#domain-management | Failed: Network error: Not Found
  Full Github Actions output

Broken runbook link in 'Documenting owners of Infrastructure'

The the service's runbook link on https://ministryofjustice.github.io/technical-guidance/standards/documenting-infrastructure-owners/#mandatory is broken - looks like the technical-guidance part of the link is missing in the path.

Could be a dupe/symptom of #63

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/standards/naming-domains.html.md.erb

• [503] https://www.gov.wales/register-and-manage-llywcymru-and-govwales-domains | Failed: Network error: Service Unavailable
  Full Github Actions output

Fix relative links so they work when published

Some relative links work in local development mode, but compile incorrectly when the site is published. (e.g. #62)

Update tagging guidance to more clearly show mandatory fields

Some teams are struggling to provide all the detail we'd like to have. It'd be nice to have a minimal set of tags we want people to use. Also, we should relegate infrastructure-support to optional, because it may often (particularly in the Cloud Platform) be the same as owner.

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/standards/how-to-get-a-domain-name.html.md.erb

• [404] https://ministryofjustice.github.io/operations-engineering/documentation/services/domain-management.html#domain-management | Failed: Network error: Not Found
  Full Github Actions output

Incomplete formatting and missing words

Not sure exactly whether this is intentional, but on technical-guidance/principles/development-principles.md there are a lot of errors in both formatting and missing words, for example, there is this:

### 1. Share the knowledge
If you have knowledge which is unique to you, it is your responsibility to share it.
We follow “[github flow](https://guides.github.com/introduction/flow/)”, to keep branches small and short-lived, and ensure knowledge is shared.
If you produce something reusable, package it (e.g. with pypi or rubygems) & share it with others on [MoJ Reuseables]( https://github.com/ministryofjustice/moj-reusables)
All non-throwaway code should be reviewed - no-one is 100% right, 
100% of the time… be aware that ‘throwaway’ code has a nasty habit of

### 2. Code should be correct, clear, concise - in that order

When you get to point 4, you've started prefixing lines with *'s to get bullets. And, what is happening with the "'throwaway' code" line?

Update to latest version of the tech-docs template

There have been a lot of changes to the tech-docs template, including the addition of search and collapsible table of contents.

It would be good to update this repo to use the latest version.

Dependabot couldn't find a Gemfile for this project

Dependabot couldn't find a Gemfile for this project.

Dependabot requires a Gemfile to evaluate your project's current Ruby dependencies. It had expected to find one at the path: /Gemfile.

If this isn't a Ruby project, or if it is a library, you may wish to disable updates for it from within Dependabot.

View the update logs.

Provide guidance for how to behave/work on call

As @myerscough mentioned on #55, we should provide guidance on things people on call should do to ensure they're available and able to support the services they're on call for, but also to make sure they're not burning themselves out.

Automate updating from tech-docs-template

When alphagov/tech-docs-template gets updates, we should pull them in. #1's commits (mostly) document the steps involved, so we should probably create a small script to do that.

Obscure space in documentation due to text wrapping

Problem with 'Documenting owners of infrastructure' (https://technical-guidance.service.justice.gov.uk/documentation/standards/documenting-infrastructure-owners.html)

Reading the docs, its hard to spot the space in <team-name>: <team-email>. due to text wrapping. The risk of leaving this unresolved, could cause inconsistency with tagging across the organisation.

Screenshot:

On this line:

technical-guidance/source/documentation/standards/documenting-infrastructure-owners.html.md.erb

Line 31 in 342e9e4

- `owner`: The team responsible for the overall service. Should be of the form `<team-name>: <team-email>`.

Central platforms should be considered outside other business units

The tagging guidance currently makes no provision for central platform-style services, of which we have a few. It should offer a business-unit value for those.

Link Checker Report

Summary

Status	Count
🔍 Total	125
✅ Successful	118
⏳ Timeouts	2
🔀 Redirected	0
👻 Excluded	5
❓ Unknown	0
🚫 Errors	0

Errors per input

Errors in source/documentation/guides/using-git.html.md.erb

• [TIMEOUT] https://twitter.com/annashipman | Timeout
• [TIMEOUT] https://twitter.com/alicebartlett | Timeout
  Full Github Actions output

Link Checker Report

Summary

Status	Count
🔍 Total	125
✅ Successful	117
⏳ Timeouts	1
🔀 Redirected	0
👻 Excluded	7
❓ Unknown	0
🚫 Errors	0

Errors per input

Errors in README.md

• [TIMEOUT] https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-github-repositories.html#technical-guidance | Timeout
  Full Github Actions output

A branch protection setting is not enabled: codeowners require reviews

Hi there
The default branch protection setting called codeowners require review is not enabled for this repository
This option affects a pull request, i.e a PR will need to be reviewed and approved by a CODEOWNER before it can be merged.
See repository settings/Branches/Branch protection rules
Either add a new Branch protection rule or edit the existing branch protection rule and select the Require review from Code Owners option
Create a .github/CODEOWNERS file
Add a or multiple entries of @ministryofjustice/team_name to the CODEOWNERS file
The team_name shall be a team from within the MoJ teams: https://github.com/orgs/ministryofjustice/teams
See GH Codeowners documentation: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
See the repository standards: https://github.com/ministryofjustice/github-repository-standards
See the report: https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/github_repositories
Please contact Operations Engineering on Slack #ask-operations-engineering, if you need any assistance

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/principles/frontend-development-principles.html.md.erb

• [ERR] https://blogs.vmware.com/vsphere/2012/03/creating-custom-metadata-using-the-vcloud-api.html | Failed: Too many redirects: error following redirect for url (https://www.vmware.com/site_maintenance.html): too many redirects
  Full Github Actions output

Bug on Safari 13 / Chrome (iOS)

In Safari and Chrome on the latest iOS (13), it appears the last bullet point of each <ul> is not clickable.

For example, on Safari on an iPhone go to:
https://ministryofjustice.github.io/technical-guidance

Try to click on:
"Frontend Development Principles"

FYI - a similar bug was found and fixed with Security Guidance - ministryofjustice/security-guidance#53

Link Checker Report

Summary

Status	Count
🔍 Total	127
✅ Successful	118
⏳ Timeouts	0
🔀 Redirected	0
👻 Excluded	8
❓ Unknown	0
🚫 Errors	1

Errors per input

Errors in source/documentation/standards/naming-domains.html.md.erb

• [502] https://gov.wales/register-and-manage-domains-llywcymru-and-govwales | Failed: Network error: Bad Gateway
  Full Github Actions output