Contributing to the Handbook

All handbook pages use the same contribution process, following these steps:

1. Making Changes to a Page

Each page in the handbook has an “Edit this page” link at the bottom that takes you directly to the GitHub source file. This is the easiest way to start a contribution:

1. Click the “Edit this page” link on any handbook page
2. You’ll be taken to GitHub where you can edit the content directly
3. If you’re not already logged in to GitHub, you’ll be prompted to sign in

2. Creating a Branch

When you make edits on GitHub:

1. At the bottom of the editor, you’ll see a “Propose changes” section
2. Enter a brief description of your changes in the first field (e.g., “Update team meeting guidelines”)
3. Optionally, add a more detailed description in the second field
4. Select “Create a new branch and start a pull request”
5. Name your branch something descriptive (e.g., update-meeting-guidelines or fix-typo-in-onboarding)
6. Click “Propose changes”

3. Creating a Pull Request (PR)

After proposing changes, you’ll be taken to the Pull Request creation page:

1. The title will be pre-filled with your brief description
2. Add any additional context needed in the description box
3. For Advice Process proposals, add the advice-process label from the right sidebar under “Labels”
4. Click “Create pull request”

4. Requesting a Review

Once your PR is created:

1. On the right sidebar of your PR, click “Reviewers”
2. Search for and select appropriate team members to review your changes
   • For small changes, one reviewer is sufficient
   • For larger changes or Advice Process proposals, select 2-3 reviewers

5. Addressing Feedback

After submitting your PR, reviewers may suggest changes:

1. You’ll receive notifications when reviewers comment on your PR
2. Address feedback by making additional commits to your branch
3. Respond to specific comments to indicate when you’ve addressed them
4. If discussion is needed, use the comment features on the PR

6. Merging Your Changes

Once your PR is approved:

1. You’ll see a green “Merge pull request” button
2. Click this button to merge your changes into the main handbook
3. Confirm the merge
4. After merging, click “Delete branch” to keep the repository clean

Your changes will be deployed to the live handbook automatically after merging.

Content Types

Advice Process Proposals

When creating an Advice Process proposal:

1. Follow the steps above to create a PR
2. Important: Add the Advice Process label to your PR
3. Use the Advice Process template
4. Notify relevant stakeholders in the PR description using @username mentions

Team Documents

When adding or updating team documents:

1. Place files in the appropriate directory under src/content/docs/
2. Follow the existing directory structure and naming conventions
3. Include frontmatter at the top of your Markdown file with:

   ---
   title: Your Document Title
   description: A brief description of the document
   ---

Weekly Memo Contributions

Weekly memos follow a collaborative process:

1. Creating the Memo:

   • If the memo doesn’t exist yet, create a new branch named memo-yyyy-mm-dd
   • Create the file in weeklies/yyyy-mm-dd.md using the weekly memo template
   • Add your content and commit to the branch
   • Create a PR called draft/yyyy-mm-dd

2. Passing to Next Contributors:

   • After adding your content, assign the next set of contributors using the “Assignees” feature
   • Add a comment mentioning them with @username to notify them

3. Final Steps:

   • The last person to contribute should tag Bomee and Erika as reviewers for the PR using the “Reviewers” feature
   • Bomee/Erika will review, merge the PR to main, and post to the #_announcements channel

Need Help?

If you’re new to Git or GitHub, don’t worry! Here are some resources:

• Ask a teammate for a quick walkthrough of your first contribution
• Post questions to the #please-and-thanks channel