Contributing
All CRUK engineers are encouraged to contribute to the guidebook by raising issues and pull requests in the GitHub repository and attending the fortnightly meetings.
Description
The CRUK Engineering Guidebook is a living document that is maintained by the CRUK Engineering community. It is a place where we can share our knowledge and best practices with each other and the world. In order to keep the guidebook up to date and relevant we use the following process.
This is our current process, but it may change in the future. If you have any suggestions for improvements, please raise them!
Process
The guidebook is maintained in a GitHub repository. The repository is currently private, the output of the guidebook remains public. Do not put any personal information or secrets in the documentation.
GitHub issues are used to track changes to the guidebook. If you have any suggestions for improvements, please raise an issue in the repository. If you have any questions about the guidebook, please raise an issue in the repository.
GitHub pull requests are used to make changes to the guidebook. These are reviewed by the CRUK Engineering community and merged into the repository. When raising a best practice pull request, please ensure that you have followed the best practice template.
All CRUK engineers are welcome to raise issues, comment on issues, raise and review pull requests. It is the essence of this document to be a collaborative effort and this why we have chosen this process.
We have fortnightly meetings to discuss the guidebook. These meetings are open to all CRUK engineers. The meetings are used to discuss issues and pull requests, and to plan future changes to the guidebook. It is also a great opportunity to meet other CRUK engineers and discuss engineering topics.
Once documents are reviewed and approved they are merged into the repository. The guidebook is then automatically built and deployed to the CRUK Engineering Guidebook. For large amendments that would be useful to share more widely we periodically publish these to the engineering slack channel.
The above steps are summarised in the diagram below.
Audit
The guidebook is audited on a regular basis. The audit is used to ensure that the guidebook is up to date and relevant. The audit is also used to identify any areas that need improvement. The audit is carried out by the CRUK Engineering community during a fortnightly meeting. Any issues identified during the audit are raised as GitHub issues and prioritized.
As well as reviewing content we also review the process. The process is reviewed to ensure that it is still relevant and that it is working well. If the process is not working well, we will make changes to improve it. This is done in a retrospective style meeting.