Skip to main content

Contributing

This playbook belongs to the entire engineering team. Improvements are welcome and encouraged.

How to propose a change​

  1. Create a branch from main following the naming convention: docs/<short-description> (e.g., docs/add-code-review-section).
  2. Make your changes to the relevant Markdown files in the repository root docs/ folder.
  3. Open a Pull Request with a clear description of what you are changing and why.
  4. Tag at least one reviewer: ideally the DRI for the section you are modifying.
  5. Once approved and merged, the CI pipeline will automatically sync the changes to Confluence.

Guidelines for contributions​

  • Keep it practical. Every recommendation should be something an engineer can act on today. Avoid abstract advice without concrete guidance.
  • Explain the why. Do not just state a rule: explain the reasoning behind it so people can apply critical thinking in edge cases.
  • Link, do not duplicate. If an external resource explains something well, link to it rather than restating it. Keep the playbook as the opinionated layer on top.
  • Respect the tone. This playbook recommends rather than commands (except in sections explicitly marked as prescriptive, like incident response). Use "this usually works best" and "critical thinking" patterns.

Confluence sync​

This repository is the source of truth for the engineering playbook. Confluence is the reading surface: it is where the team (and clients, where relevant) reads the content.

Do not edit synced pages directly in Confluence: your changes will be overwritten on the next merge.

To preview changes locally before opening a PR, run from the repository root:

npm install
npm start

Then open http://localhost:3000.