Handbook contribution

On this page

• How to edit the handbook
  • Edit workflow
    • Creating a new page
  • Handbook structure
    • Internal links
    • Frontmatter
    • Table of contents
  • Repository vs site
  • Handbook style guide

How to edit the handbook

The handbook’s content is written in Markdown format. Familiarize yourself with the syntax before doing your first edits.

For simplicity, GitHub’s web UI is the proposed choice of editor for markdown files, and that which the workflow below assumes. Alternatively, more advanced users can also choose to check out the repository, do local edits and submit the changes in a PR.

Creating and curating the handbook is a collaborative effort where everyone in the team is encouraged to contribute. Since often the content will define common policies or processes, it will also be peer-reviewed. The act of doing reviews and approvals will generally be a compromise between consensus and bias for action. Everyone is encouraged to do a review, but the submitter will not generally require approval from the whole team to commit their changes, so that we can move faster. Exceptions might include defining critical team policies, where everyone’s review and approval might be required before that policy is either approved, iterated upon or discarded.

Edit workflow

Content contribution overview:

graph TD
    A(Edit content) --> B_(Commit changes)
    B_ --> B("Submit Pull Request (PR)")
    B --> C(Request review)
    C --> D{Reviewer approves}
    D -->|Y| E(Merge PR)
    D -->|N| F(Edit content)
    F --> G(Commit changes)
    G --> C

Content contribution in detail:

Stage	UI	Description
Edit		At this stage you are viewing the file you want to edit on the handbook repository. Any text file will have a pencil icon at the top right-hand corner, which you can click to start modifying the file on the web editor. This workflow will initiate the creation of a development branch to contain your changes on the main repository.
Commit changes		Once you are ready with your changes, you will want to commit them to save them under revision control. Scroll down to the bottom of the file you are editing to find the commit dialog. Generally for commits you’ll want to fill in the short description only. Make sure you are using your @linuxfoundation.org e-mail address for the sign off You can use the default for the branch name, or you can choose a name for your branch Finally click on Sign off and propose changes to commit those changes.
Submit Pull Request (PR)		Once the changes have been committed, GitHub will start the process of creating a PR, opening a similar dialog as in the previous stage. You can now review the description and changes before you submit the PR. The short description will be the title of the PR. By default, GitHub prepopulates it with the short description of your last commit. Review it to ensure it describes the PR’s purpose accurately It’s recommended to fill in the long description for PRs. This provides context for the reviewers to understand why you are proposing changes vs. what the changes are. If your PR is a work in progress and you want to continue adding changes before it is reviewed, choose Create draft pull request. Otherwise choose Create pull request. Then click on the button to create it.
Request review		Once your PR has been submitted, a reviewer or more should be assigned to it for the ultimate review and approval. Pick one or more reviewers from your team, on the Reviewers section on the right-hand side panel of the web UI. Alternatively, you can also ask for a review by explicitly asking (mentioning) people on one of the PR’s comments
Reviewer approves	TBD	The reviewer will get an e-mail notification. Once they are ready to review, they will generally look at the Changes tab to see a diff of what’s been modified. If they are happy with the changes, they will approve them. If not, they’ll point out what they feel needs to be changed for the submitter to address it. In that case, the reviewer will go back to the file in their branch, and restart the edit and commit process, which will automatically update the PR.
Merge PR	TBD	The final reviewer will generally merge the PR once one or more approvals have been received. The submitter will not generally approve their own requests. However, until we refine the process it should be fine for them to do so if the reviewers’ approvals have been done.

Note for advanced users: members of the Developer Experience and Community Success team in the linuxfoundation organization in GitHub can create development branches directly under the repository where the handbook lives. These will be generally the ones that will be used to contain the changes submitted in PRs. It is not the most common development approach, but it simplifies our workflow. Working on forks and topic branches is also supported.

Creating a new page

While the edit workflow mostly applies, for new pages an extra step needs to be taken to initially create the markdown file that will include the content. Follow these steps on the handbook’s GitHub project to create a new page from a template:

1. Navigate to the the _new_page template page
2. Click on the <> icon at the top of the file to display its source
3. Copy the contents of the file
4. Navigate to the location of your new page. This will generally be under one of the top folders under the handbook folder itself. E.g. /workflows
5. Choose the Add file » Create new file menu option on the top right hand side of the GitHub UI
6. Name the file appropriately (lowercase, using hyphens - if necessary)
7. Paste the contents of the template file you copied on step 2
8. Edit the frontmatter appropriately. If needed, learn more about the frontmatter.
9. Commit changes and submit a PR as per the Edit workflow

Handbook structure

The handbook’s structure is conceived to be initially simple. The front page’s content goes onto the top-level README.md file.

If content needs to be added to its specific section (e.g. a lengthy, self-contained topic), it can also go into a new subpage. In practical terms, the subpage will be a folder in the root directory of the repository, which will include a markdown file with the content. Generally, the subpage will be linked to from somewhere else in the handbook for discoverability. Nested folders are supported by using the just-the-docs theme.

Internal links

To add internal links to a subpage, use the regular Markdown link syntax and the name of the subpage, which will be the same one as the folder that contains the README.md file with the content. That is, all links are relative to the top handbook folder. Example:

All team members are [encouraged to contribute to the handbook](edit-this-handbook).

Internal subsections (anchors) can also be linked. You can hover over a section and from your browser find out its URL to put on the internal link.

All team members are [encouraged to learn about the handbook structure](edit-this-handbook#handbook-structure).

The links in the README.md files will automatically be converted to valid, relative HTML links when the handbook site is rendered.

Frontmatter

Each page needs to include some metadata content at the top. The format for this metadata is based on Jekyll’s frontmatter (Jekyll is the static site generator that renders the handbook site), and is used by the handbook site’s theme (just-the-docs) to define the navigational structure

An example of frontmatter can look like this

---
layout: default
title: Customization
nav_order: 4
permalink: /workflows/my-workflow
---

Mostly the frontmatter can be copied over and filled in from the contents of the _new_page template page. For more elaborate uses of frontmatter (e.g. to create nested top-level sections), refer to the just-the-docs theme documentation

Table of contents

While GitHub’s web view of the README.md files does not support an auto-generated Table of Contents (TOC), this can be added to the rendered content on the site. Simply add this snippet on top of each README.md file:

## On this page
{:.no_toc}

* TOC
{:toc}

Learn more about this syntax.

Repository vs site

The handbook is hosted on GitHub as a set of files written in plain text formatted as Markdown. Given that GitHub renders README.md and some other files as HTML when navigating through a repository, most of the handbook content can be consumed directly from the repository itself through the browser.

The handbook is also set up to use GitHub Pages, which automatically render the Markdown files into rich HTML pages hosted on a dedicated site with its own URL. Consuming the handbook content through the site is recommended for most users, as it provides a cleaner, read-only user interface with added features, such as Tables of Contents.

The website is updated and deployed every time a PR is merged. GitHub Pages uses Jekyll as the static website generator engine to serve the content. At this time, running the site on a local machine is not supported for simplicity’s sake, but could be set up in the future to ease local edits and testing.

Handbook style guide

1. The handbook represents the current state and is assumed to be up-to-date. Do not document historical content or future states, unless explicitly describing a roadmap, mission or vision.
2. Use GitHub flavored Markdown format to write content
3. Use sentence case for section titles
4. Use only one H1 header (# in Markdown) as the top level header for section title. Child sections will continue as H2 (##), H3 (###), and so forth. Strive to keep a shallow title depth for simplicity.