This is the contribution guide for the Home Office Software Engineering Guidance and Standards, we commonly refer to as SEGAS. This guide will cover the primary way we expect contributions to be made, which is adding new principles, standards, guidance and patterns.
To contact the team you can get us at [email protected]
Please read and follow our Code of Conduct.
Please find some helpful links to guide you in starting your journey with open source.
- To get an overview of our project please see our README.
- Collaborating with pull requests
- See the benefits of Open Source
We will now look at the process we expect contributors to take when suggesting fixes, new content or a review of existing content.
- Before submitting an issue, please search the issue tracker to check the issue is not already there.
- Please create an issue if you wish to:
- report a bug
- propose a new pattern
- propose a new principle
- propose a new standard
- review any existing content
- report a security vulnerability
- Have a look at our existing issues, and you might find something you would like to help us on!
To start the process of making changes to an issue you have raised, firstly you should fork our repo. This is so you can make changes without affecting the original project until you're ready.
Please create a branch using the default GitHub branch naming strategy which is based off the issue you are working on.
If you are updating a small piece of text, a typo or broken link, then you can edit the file directly from GitHub. Click the make a contribution button which will open the file in the GitHub user interface. If you haven't already, when starting this, GitHub will automatically create a fork of our project into your account.
If the change is more substantial, then you may want to get the code and run it locally. If you take a look at our README, there are instruction on how to do this.
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!
When you're finished with your changes you should create a pull request, commonly known as a PR.
Find some helpful information on how to create GitHub Pull Requests.
When creating a PR, use the appropriate template checklists for code and content changes.
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.
Congratulations, your contribution is now merged into the project and you have improved and added value to an on-going open source project. Thank you!
Currently we are using Cypress to do end to end tests. As this is a static site, these are lightweight and check that any changes continue to build front page links correctly.
Please add to these where you feel necessary.
There are no integration tests currently being used in this repo. As the site is built using the Cross Government Eleventy plugin and mark down files, there is limit scope to do this.
However, if you feel that some changes are becoming more complex, then you may want to consider adding these in.
We are using GitHub workflows for build and deploy and automated end to end testing.
The following actions are performed for each PR:
- Automated end to end testing using Cypress.
PRs must only be approved after they pass the above checks.
We are deploying the site to a Docker container.
We are using a simple trunk based strategy.
You can tag any of the maintainers of this repo to get pre-pull request reviews and start discussions. We are a friendly team so please feel free to tag us!
Patterns, principles and standards should be created in the correct subdirectory in /docs. We are also using a tagging and metadata approach to organise content across the site by topic and related knowledge domain.
All patterns, principles and standards content should be tagged in the frontmatter of the .md file to reference at least one of the below topic domains. Follow the guidance on tagging from the 'writing a standard' standard.
- Observability - the process of monitoring applications, services and reliability
- Software Design - how our applications, services and software are architected at the software level
- Security - making our applications, systems, services and ways of working resistant to cyber attacks
- Ways of Working - engineering teams patterns for approaching work
- Build, Release and Deploy - all things pipelines, building and platform engineering
- Source Control - storing and managing the source code
You can view a list of all the topic domain tags currently in use across the site. Your content may cross cut many of these areas, and that is ok, tag everything that you think is relevant.
When creating content please take a look at the standard for that content. This helps to make sure we are all creating content correctly.
You can use the following templates when creating content: