Editing the handbook

Every Sourcegraph teammate will be editing the Sourcegraph handbook frequently to keep information up-to-date and participate in important changes in the company. This guide helps everyone learn how to edit the handbook.

The handbook consists of Markdown files in the Git repository at github.com/sourcegraph/about. (Why not a wiki or Google Docs?)

How to get help

We don’t expect everyone on the team to figure this out on their own. Other teammates are happy to help!

  • Any engineer at Sourcegraph can help. (The code that engineers write at Sourcegraph also consists of files in a Git repository, so engineers are very familiar with making these kinds of edits.)
  • Teammates who have already made a handbook change can help.
  • Handbook heroes: Ask @eric, @aileen, or @aharvey for handbook help on Slack (DM or #handbook). They volunteered to help anyone with anything handbook-related!
  • Ask in #handbook: Who can screen-share with me to help me make an edit to the handbook?
  • Don’t be afraid of breaking anything! It is very easy for any engineer on the team to roll back to the previous version of the handbook if you make a mistake.


Here’s the process for getting a change published to the handbook. For detailed step-by-step instructions (intended for people who are new to Git), see the sections below.

  1. Propose the edits you want to make by creating a pull request on the Git repository at github.com/sourcegraph/about.
  2. You can request a review from specific teammates (who will get a notification) on the GitHub pull request page.
    • We don’t have any rules around who needs to review what changes. Use your judgment (e.g., if your change affects the entire engineering team, request review from the VP Engineering).
    • For minor edits, you can skip review.
  3. Wait for the necessary teammates to review and approve your pull request.
  4. Merge the pull request.
  5. Wait up to 5 minutes for your change to be live on about.sourcegraph.com.

Reviewing and approving another person’s proposal

Frequently used links:

Edit a single file

If you just need to edit a single page, you can do it entirely on the web.

  1. Visit the handbook page you want to edit on about.sourcegraph.com.
  2. Press the Edit this page button in the sidebar.
    • If you don’t see it, you may be viewing a page on about.sourcegraph.com that is not part of the handbook. Handbook pages all have the same design as the main handbook page. If it has a different design, ask for help.
  3. In the text editor, make your edits.
    • The document is in a format called Markdown that lets you use headings, links, bold, lists, etc., in a plain text file. See “Mastering Markdown” and feel free to ask for help.
  4. Switch back and forth to the Preview changes tab at the top of the editor to see the nicely rendered page with your edits applied.
    • Deletions are shown in red, changes are shown in orange, and additions are shown in green.
  5. When you’re happy with your edits, scroll to the bottom of the page to the Commit changes box.
    • Type a short, one-line summary of your change in the first text field (instead of the default Update filename.md text).
    • Type a more detailed explanation of your change in the larger text field.
    • Select the Create a new branch for this commit and start a pull request option (if it’s not already selected).
    • Press the Commit changes button.
  6. Press the Create pull request button. Now your change has been proposed!
  7. Select teammates to review using the Reviewers button on the right side of the pull request page.
  8. Wait for teammates to review, comment on, and approve your pull request.
  9. When you’re ready to publish the change and make it live, press the Squash and merge button, then press Confirm squash and merge.
  10. Wait up to 5 minutes for your change to be live on about.sourcegraph.com.

Edit multiple files or add a new file

To make edits to multiple files and submit all of the edits as a group to be reviewed together, you will follow a more complex process than when editing a single file. This also is required for adding new files.


Here’s a screen recording of the steps (written out below) for macOS:


  1. Download and install GitHub Desktop.
  2. Launch GitHub Desktop and sign into it using your GitHub username.
  3. Clone the sourcegraph/about repository (assuming to the ~/Documents/GitHub/about folder on your computer).


  • Use Typora to edit and preview Markdown (.md) files.


  1. In GitHub Desktop, open the about repository that you cloned previously.
  2. In Current Branch, select main if it’s not already selected.
  3. Press the Fetch Origin button to get the latest contents of the repository.
  4. In Current Branch, create a new branch with a short name (like add-travel-guidelines, no spaces or punctuation).
  5. Edit files in the ~/Documents/GitHub/about/handbook folder on your computer.
  6. When you’ve edited the files and saved your changes, GitHub Desktop will show you the changed files in the left sidebar. Confirm that your changes look good by viewing the diffs for each file.
  7. In the bottom left Summary (required) text field, type your commit message (a one-line description of the change) and a longer Description below.
  8. Press the Commit to add-travel-guidelines button (where add-travel-guidelines is the branch name you chose earlier).
  9. Press the Publish branch button.
  10. Press the Create Pull Request button.
  11. On the pull request page in your web browser, select reviewers and wait for reviews/approvals, then merge to make the changes live.

Uploading large files

If you want to upload a large file (such as a large image, video, or audio recording) and make it available in the handbook, upload the file to Google Drive and then get a shareable link to the file on Google Drive. Add that link to the handbook. Don’t add large files to the handbook repository itself (because Git is not a good way to store large non-text files).

Running a local preview handbook site

See the handbook section in the repository README.