Skip to main content

Contributing

tip

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 maintained by the CRUK Engineering community. It’s a place where we share our collective knowledge, best practices, and guidance to continually improve the quality and consistency of our engineering work. As a living resource, it evolves over time with the contributions and insights of our community.

Getting Started​

If you’re new to contributing, here are a few steps to help you get started:

  1. Clone the Repository:
    If you’re a CRUK engineer with access, clone the private repository.

  2. Set Up Locally:
    Install any necessary dependencies (refer to the README.md in the repository), and run the guidebook locally to review changes in context.

  3. Review Templates:
    Ensure your issue submissions include clear, concise information such as the problem being addressed, the proposed change, and any relevant examples. Follow the repository's best practices for formatting and clarity when proposing changes.

  4. Familiarise Yourself with the Structure:
    Browse through the existing sections of the guidebook to see where your contribution best fits. This will help ensure your updates are placed logically and are easy for others to find.

Process​

The guidebook is maintained in a GitHub repository. While the repository is private, its output is publicly accessible. Do not put any personal or sensitive information in the documentation.

  • Issues:
    Use GitHub issues to suggest improvements, ask questions, or highlight areas needing clarification. If you spot outdated content or want to propose a new best practice, open an issue to start the discussion.

  • Pull Requests (PRs):
    Make changes through PRs. Follow the best practice template if you’re adding or updating a best practice. Your PR will be reviewed by other CRUK engineers for accuracy, clarity, and alignment with our standards before it’s merged.

  • Collaboration & Review:
    Any CRUK engineer can raise issues, comment, and review PRs. We value constructive feedback and encourage incremental improvements. If you’re unsure about an approach, comment on an issue or PR to start a conversation.

  • Meetings:
    We hold fortnightly meetings open to all CRUK engineers. At these sessions, we discuss outstanding issues, review PRs, plan upcoming updates, and share engineering insights. To join, look for the recurring meeting invite in your CRUK calendar or check our dedicated Slack channel (#engineering-guidebook) for reminders and agendas.

  • Deployment:
    Once changes are approved and merged, the guidebook is automatically built and deployed. For major updates, we announce them in the engineering Slack channel to keep everyone informed.

Below is a visual overview of the contribution process:

Audits​

We regularly audit the guidebook to ensure it remains accurate, up to date, and aligned with current engineering practices. Audits typically take place during our fortnightly meetings and may highlight outdated information, gaps in coverage, or areas needing further clarification. Any issues uncovered are raised as GitHub issues and prioritised for resolution.

In addition to reviewing content, we periodically examine our contribution process to ensure it remains effective and efficient. If the process isn’t working as intended, we discuss improvements in a retrospective-style meeting and adjust accordingly. This continuous feedback loop helps the guidebook and its processes evolve alongside our engineering community.