Bramble

Editing The Handbook

Help is available for team members

We don’t expect you to figure this out by yourself. If you have questions, ask anyone for help or post in the #handbook Slack channel. You’re more likely to have success with:

  • People that have Merge Request buddy as an expertise on the team page.
  • People that have been here longer than 3 months. The team page lists people in order of how long they have been here.
  • People that have ‘engineer’ in their title.
  • We encourage you to meet someone new by asking someone you don’t know for help. You can also ask for help in #questions or #peopleops by posting ‘Who can do a video call with me to help me work on the website locally /handbook/git-page-update/ ?’. If the other options don’t work for you, please ask your onboarding buddy.

Markdown Guide

Most pages that you might want to edit are written in Markdown.

Read through this Markdown Tutorial to understand its syntax and create new content.

Editing using Forestry.io

Forestry.io is a web-based CMS that works with our statically generated site, so you can make edits in your browser, provided you have been granted access to do so in our Forestry.io account.

This is the fastest way for minor edits, that can be made on Staging (or Master) directly. However because it doesn’t use Merge Requests, its a little harder to manage reviews and approvals if you use Forestry, so avoid it for larger edits please.

Our Handbook git repo is sychronized with Forestry, and we use two Forestry Sites (aka projects):

  • Staging
    • Start here if you’re not sure
    • Edits wont be deployed immediately (unlike master). They are committed to the staging branch.
  • Master
    • YOLO mode. Edits will be deployed immediately (without review)
    • You may need to request access to this Forestry Site

New Handbook pages

  • Select the folder you want to put the page in (using the Forestry file browser)
  • Click Create New
  • Click Handbook to select the Handbook frontmatter template
  • Make edits
  • Save Draft as you go (optional, unless you are working on master)
  • click Draft -> Off and Save

Previewing your edits

Forestry.io provides a WYSIWYG editor that allows you to edit both the FrontMatter and the page content easily.

It also provides a site preview so you can see what your edits look like in the website.

Merge

Changes made in the staging site in Forestry go into the staging branch.

To get your edits live, a GitLab MR will need to be (created and) merged with master. This happens in GitLab (not Forestry).

  1. Assign the staging MR to the Directly Responsible Individual (DRI):
  • If the DRI for the page(s) being updated isn’t immediately clear, then assign it to your manager.

Editing using the WebIDE

This is another way of editing the Handbook in the browser. The GitLab Web Integrated Development Environment (IDE) can be used to make changes within the browser. This method requires no setup, and works well with Merge Requests and reviews.

  1. Find the handbook page to edit.
  2. Click on the Edit in Web IDE link at the bottom of the page.
  3. Edit the page using MarkDown. You can preview your changes (but links will not work).
    • Note: You can edit other pages by browsing through the filelist on the left side in the Web IDE.
  4. After making your changes, click the Commit... button in the bottom left to review the list of changed files. Click on each file to review the changes and click the tick icon to stage the file.
  5. Once you have staged some changes, you can add a commit message and commit the staged changes. The message should be as brief as possible, since it has a character limit. You can add more detail in the description in a subsequent step. Unstaged changes will not be committed.
  6. Choose the option to create a new branch and create merge request. For your branch, use a descriptive name with hyphens and no spaces, so that you can find it again later, but it’s temporary so don’t worry too much about the exact name. We recommend the format your initials/team-page-update-yourdepartment-the date Example: lg/team-page-update-custsupport-feb06.
  7. Submit and you will be taken to the merge request (MR) page.
  8. Feel free to add a more detailed message in the description box. For the options, check Remove source branch.
  9. Assign the MR to the Directly Responsible Individual (DRI):
  • If the DRI for the page(s) being updated isn’t immediately clear, then assign it to your manager.

Editing Locally

  1. If you haven’t already, go through the Editing Locally setup steps below.
  2. The handbook lives under content/handbook/. For the most part, you can locate the specific item to edit via that item’s URL. For instance, this page is /handbook/git-page-update/ and its source lives in content/handbook/git-page-update/_index.md.
  3. Edit away! See the Start Contributing section for details about the Markdown that most pages are written in.
  4. Preview your changes locally by following the directions in README.md. The great part about developing locally is that the Hugo server will auto-reload when you change a page!
  5. Once you’ve made your changes and verified they appear the way you want them to, commit them with a comment and push your branch.
  6. As above, Create a Merge Request in the handbook project. If you’re onboarding, don’t forget to assign it to your manager.

Marking a MR as a Work in Progress (WIP)

  1. You can easily prevent a merge request from being merged before you’re ready by marking it as a work in progress. Simply type “WIP:” at the beginning of your merge request title (e.g. “WIP: My Handbook Change”). To merge once you’re ready, edit your MR and remove “WIP:” from the title.
  2. Note: Only mark a merge request as “WIP” (Work in Progress) if it will negatively affect the company if merged too early. That can be the case for application code but is almost never possible for handbook MRs.

Ready to merge

Handbook Merge Requests should have the branch set to delete. If the change relates exclusively to a particular area, you can have the commits set to squash. (If they are disjoint, dont worry about squashing) Then assign the MR to a maintainer for review and merging.

Setup for Editing Locally

This is a guide on what you’ll need to install and run on your machine so you can make edits locally. This is quicker than in the web interface and allows you a better overview and preview when making complex changes. Once you’re set up, you will find the source files for the Bramble Handbook here /source/handbook/

Start using GitLab

  1. Here’s where you can find step-by-step guides on the basics of working with Git and GitLab. You’ll need those later.
  2. Create your SSH Keys.

Install Git

  1. Open a terminal.
  2. Check your Git version by executing: git --version.
  3. If Git is not installed, you should be prompted to install it. Follow this guide to installing Git and linking your account to Git.

Clone the source of the website and install its dependencies

  1. If you set up SSH keys previously, in terminal execute: git clone git@gitlab.com:brmbl-io/www.git to clone the website. If you prefer using https, then execute: git clone https://gitlab.com/brmbl-io/www.git, but note that if you’ve activated 2FA on your GitLab.com account, you’ll need to take some additional steps to set up personal access tokens. If you ever want to switch between SSH and https, execute git remote remove origin, followed by git remote add origin [..] where the [..] is the part that starts with git@ for SSH, or with https: for https.
  2. Execute: cd handbook to change to the handbook directory.
  3. Install additional dependencies Golang and hugo. If not installed, step 6 may result in an error.

Prevent newlines from causing all following lines in a file to be tagged as changed

Git is able to automatically convert line endings between CRLF and LF and vice versa. Execute the following command to configure Git to convert CRLF to LF on commit but otherwise leave line endings alone:

git config --global core.autocrlf input

If you’d like to learn more about Git’s formatting and whitespace options see the “Formatting and Whitespace” section under “Git Configuration” in “Pro Git”.

Preview website changes locally

  1. In a terminal, execute:
    1. Change to the directory for your site, for example: cd handbook
    2. make dcup.
  2. Wait for the log line: Web Server is available at http://localhost:1313/
  3. Visit http://localhost:1313/ in your browser.
  4. You will need to install a text editor to edit the site locally.
  5. Refresh your browser to see your changes.

Start contributing

Start writing pages! Its just Markdown.

You can copy existing pages as a starter - preserving the YAML FrontMatter tags (the stuff like title:, layout: etc inside the --- at the top of each markdown page). If you use Forestry, just select “Create New -> Handbook Page”, which has this front-matter in the template.

For the most part its straightforward - particularly for Handbook Pages. Some website pages however are a little trickier, as they use HTML, not Markdown. Instructions on how to update the website part of the Handbook are in the readme of handbook.

Test if all URL links in a page are valid

Until this is automated in CI, here’s some ways to check if there are any invalid links inside a page:

Using our test script (htmltest)

  1. In a terminal, execute:
    1. Change to the directory for your site:
    2. make test.

Using a Browser Plugin

  1. Install the check-my-links extension in Chrome or the Broken Link Checker addon in Firefox.
  2. Open the page you wish to preview (see previous step).
  3. Click the newly installed extension in the upper right corner of Chrome.

A pop-up window will open and tell you how many links, if any, are invalid. Fix any invalid links and ideally any warnings, commit and push your changes, and test again.

  • All internal links (links leading to other parts of the website) should be site root-relative.*
Contribute: Edit in Forestry Edit in Web IDE View Source