Contributing to the Handbook

March 9, 2026 · View on GitHub

This guide aims to make it easier to submit changes to the Handbook without using git or a text editor.

Updating and adding pages in Github

Creating a page

  1. Go to the handbook.
  2. Click through to the folder you want.
  3. Click "Create new file"
  4. Type out your contents under "Edit new file" using Markdown.
  5. Preview your changes at any time by clicking "Preview".
  6. When you're happy with your page, write a short description under "Commit new file". For example, "Add Flexible Holiday Page".
  7. Select "Create a new branch for this commit" and give it a name relevant to your change. For example, "add-flexible-holiday-page".
  8. Submit the change by clicking "Propose new file".
  9. You will then be able to create a Pull Request to get a review of your new page. Click "Create pull request", then share the link with people!

Updating a page

  1. Go to the handbook.
  2. Navigate to the page you wish to update.
  3. Click the pencil button in the top right
  4. Make the necessary changes using Markdown.
  5. Preview your changes at any time by clicking "Preview".
  6. When you're happy with your page, click "Commit changes" and write a short description under "Commit message". For example, "update pension scheme page to include the people team email"
  7. Select "Create a new branch for this commit" and give it a name relevant to your change. For example, "update-flexible-holiday-page".
  8. Submit the change by clicking "Propose changes".
  9. You will then be able to create a Pull Request to get a review of your new page. Click "Create pull request", then share the link with people!

Addressing review

  1. Click on the "Files changed" tab on your Pull Request.
  2. Click on the pencil icon in the toolbar above the file content.
  3. Make your changes as before, previewing until you're happy with them.
  4. Under "Commit Changes" describe what this change does. For example, "Fix typo" or "Extend section on getting a company credit card".
  5. Keep the selected option as "Commit directly". You don't need to create a new branch for every change.
  6. Press "Commit changes".

There is a GitHub Actions Workflow that checks for broken links in the Handbook.

If you see "Some checks were not successful" above the "Squash and merge" button on the pull request overview page, click through to the failing check for the details of the broken links.

You will see something like this:

> @madetech/handbook@1.0.0 test
> node build.js

 [dead(400)] ../../benefits/free_bananas.md in guides/welfare/breakfast_is_important.md
Broken links found
Error: Process completed with exit code 1.

This example is telling you that there is a link to the benefits/free_bananas.md page in the guides/welfare/breakfast_is_important.md page that does not work. It should be straightforward to find the link and correct or remove it as required

Finalising the change

  1. Get feedback from the wider company and address any feedback. Once you've had your Pull Request approved, you're ready to finalise your change.
  2. On the "Conversation" tab of your Pull Request, click "Merge pull request".
  3. Your new page will now be visible in the Handbook.

Approval and merging

There are broadly two types of change to the handbook, each with a different approval flow. If in doubt, default to the strictest method (Significant changes or additions) or ask for advice on Slack.

  1. Significant changes or additions
  2. Uncontroversial clarifications

1. Significant changes or additions

This includes changes to policies, changes to the way people are expected to work, changes that express a departure from a previous community norm, etc.

  1. Open a pull request
  2. Shout about the pull request in all relevant Slack channels. This should include announcements, but if it relates to a particular part of Made Tech, also in the channels more relevant to those people.
  3. Allow enough time for people to review and comment, remembering that they probably have busy schedules. One to two weeks is probably sensible.
  4. Manage the conversation, seek approvals on GitHub, address feedback.
  5. When it feels like something close to consensus is established, merge.

Consensus is subjective, and we can't make a rule that catches all the important ways it can look. If you're unsure if you've got enough of it, reach out to the community on Slack.

2. Uncontroversial clarifications

This includes spelling mistakes, poorly worded sections, and writing something down that we all are doing anyway.

  1. Open a pull request
  2. Shout about it in relevant channels
  3. Address feedback
  4. Wait for an approval
  5. Merge

Getting permission to contribute to the Handbook

You may find that you don't have write permissions on the handbook. Here is how to contribute:

Made Tech employees

If you are a Made Tech employee, it is as simple as asking the IT service team for access to the GitHub Made Tech Software team (you should be able to access IT Services on Slack or on your Desktop).

Once you're part of the MT Software Team, it is as simple as following the instructions above. When you create the PR, if you're not asked to create a fork of this repo, then you're on the good path. If you are asked to create a fork, please speak to IT services to ensure you have write access to the handbook.

Non Made Tech folks

Hello! 👋 Thank you for taking the time to contribute to the handbook! However, once you get to the PR phase, you may find your PR is stuck waiting for the CI/CD pipeline to trigger. This is intentional - to get your changes merged, you'll need to request access to a MT employee with write permissions on this repo.

If you are a MT employee with write permisssions, here is how to trigger the CI/CD process for forks:

  1. Go to the fork's repository and grab the repo URL (e.g. git@github.com:sohebmahmood-madetech/handbook.git)
  2. On your machine, navigate to the handbook git repo, and add the URL as an additional remote repo
git remote add <user friendly repo name> <repo>

e.g.

git remote add sohebmahmood-mt git@github.com:sohebmahmood-madetech/handbook.git
  1. Fetch the newly added remote
git fetch <user friendly repo name>

e.g.

git fetch sohebmahmood-mt
  1. Checkout the branch
git checkout sohebmahmood-madetech/patch-1
  1. Rename it locally to a branch name that is less likely to cause conflicts when pushed into the origin remote
git checkout -b sohebmahmood-mt-patch-1
  1. Push into origin
git push origin sohebmahmood-mt-patch-1

This should be enough to trigger the CI/CD pipeline to do the build locally. If the build fails, any new changes will most likely need to be pulled in and pushed into the origin branch until the build passes.

Once the build passes and you get the relevant approvals, feel free to merge the changes into the handbook. Once the PR is merged, please delete the branch from origin (it is as simple as going to the Handbook home page, click on Branches, finding the new branch and pressing the delete icon next to it).