contributing_to_the_handbook.md

Contributing to the Handbook

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 be then be able to create a Pull Request to get 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 be then be able to create a Pull Request to get 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".

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 most strict 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 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 of 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 pull request
2. Shout about it in relevant channels
3. Address feedback
4. Wait for an approval
5. Merge