Proposed standard: .SEGAS file in base of repo to describe engagement with SEGAS standards

[GraemeSutherlandHO]

Our engineering standards are the things that we expect engineers to do. Look at the 'writing a standard' standard and provide some brief information below

What is the standard you are suggesting?
.SEGAS file in base of repo to describe engagement with SEGAS standards

What would be the benefit to the Home Office of adopting this standard?
Foster engagement with SEGAS standards by engineers. Be able to test engagement with standards by pipeline. Be able to report on SEGAS engagement/conformance.

How might people follow it
When a repo is created for a product or part of a product, a .SEGAS file is added to the root of the repo which lists, for each standard:

• standard name and version
• assertion whether standard is met or not
• commentary/reason

For example:

{
    "SEGAS-00003": {
        "version": "1.2.3",
        "met": false,
        "reason": "We currently don't have a decision log"
    }
}

Please confirm the below

• I have looked at the writing-a-standard standard and think this would meet the standard
• I have looked through our existing standards and think this is not covered elsewhere
• I have checked through the open issues on the repository and this standard has not already been suggested

[GraemeSutherlandHO]

Standards may need clear versions for this to work properly.

[GraemeSutherlandHO]

potential for a little tooling to review current .SEGAS against current latest standards and report.

[daniel-ac-martin]

I agree that we need to track compliance with the standards, I'm not sure that can/should be done on a per repo basis though. The reason being that surely some standards will span multiple repos, or even apply more to ways of working than to the code itself?

That said, I'd think that there would be some standards that could be monitored on a per repo basis.

[GraemeSutherlandHO]

Can we add assertions for multiple repos in on .SEGAS?

[mikewaldnerscottwork]

This issue was discussed on the Ways of Working guild call on 16/5/24 (3pm)
@robertdeniszczyc2 and @aaronrussellHO gave context on previous discussions over and above what is discussed her
The results of #408 were shared - the pull request was merged.
The resulting json file - https://engineering.homeoffice.gov.uk/standards.json to be used for an initial, limited scope alpha trial, as follows:
1 - The DSA Cloud Infrastructure & Tooling team to deploy json file to internal repos in GitLab (probably all of one group of repos)
2 - Staff to volunteer to assess the repos for compliancy and update
3 - Set up runner with read rights to scan repos and provide a PoC dashboard for results (Grafana? PowerBI?)
4 - UAT notes on experience, snags and comments to be collated
Challenges:
1 - There may need to be work to define numerical values to IDs in the json for alerting via dashboard
2 - Ensure UAT notes are measurable and a retro can be done on them

[aaronrussellHO]

Thanks for volunteering for this @mikewaldnerscottwork. I would also speak to @GraemeSutherlandHO as he came up with it initially and may have more insights.

[mikewaldnerscottwork]

Thanks for volunteering for this @mikewaldnerscottwork. I would also speak to @GraemeSutherlandHO as he came up with it initially and may have more insights.

Great point, yes - @GraemeSutherlandHO happy to discuss further.

[mikewaldnerscottwork]

PoC now up and running - test repo has been scraped into central page. Currently in Confluence. Next step - document and look to move into a central area (maybe Core Cloud) for further scope and alpha stage plans.