Contributing to Documentation

How to contribute to the Project Tetra documentation

These guidelines assume that you’re familiar with the GitHub workflow.

How to Contribute

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Creating an issue

If you’ve found a problem in the docs, please create an issue in the Project Tetra docs repo. You can also create an issue about a specific page by clicking the Create documentation issue button in the top right hand corner of the page.

Updating the site

Here’s a quick guide to updating the site:

  1. Create a new branch, or checkout an existing branch, in the Project Tetra docs repo. The branch name should be prepended with its associated issue label followed by a /, followed by a dash-separated description of the changes to be made, followed by its associated issue number, e.g., feature/add-tricoder-with-touchscreen-docs-1701. If no such issue exists, create a new issue.

    Note: If you haven’t been added as a collaborator to the Project Tetra docs repo, you will need to either fork the repo or contact the repo admin to request write access. The repo admin can be contacted via the HelpfulEngineering slack group on the #project-tetra channel.

  2. Commit your changes and create a pull request (PR). Be sure to include a closing keyword followed by the associated issue number in the PR description, e.g., closes #1701. If the pull request closes multiple issues, add a closing keyword for each issue. (See closing issues using keywords.

  3. If you’re not yet ready for a review, mark the PR as Draft to indicate it’s a work in progress. Continue updating your doc and pushing your changes until you’re happy with the content.

  4. When you’re ready for a review, mark the PR as Ready for review.

  5. Once your PR is merged, you may safely delete your branch.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

  1. Click Edit this page in the top right hand corner of the page. The appropriate page will be displayed in edit mode.

    Note: If you haven’t been added as a collaborator, you will be prompted to fork the repo or update your fork of the repo - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit.

  2. Follow the rest of the Updating the site process to propose your changes.

Running the website locally

You can run your own Hugo server using docker to preview the site locally:

  1. Install docker.

  2. Clone the Project Tetra docs repo. Don’t forget to use --recurse-submodules or you won’t pull down some of the code you need to generate a working site.

    git clone --recurse-submodules https://github.com/tetrabiodistributed/project-tetra-docs.git
cd project-tetra-docs

    Note: If you accidentally cloned without using --recurse-submodules, you can run git submodule update --init --recursive to pull down submodules needed to generate a working site.

  3. Run the build.sh script in the site root directory (Note: Linux users may need to prepend this command sudo). This will build a docker image, as well as install node modules, needed to locally run the project-tetra-docs Hugo webserver. Once the image is built and stored on your machine, you do not need to rerun this step. You can view all locally installed images by running docker images.

    ./build.sh

  4. Run the serve.sh script in the site root directory (Note: Linux users may need to prepend this command sudo). By default, your site will be available at http://localhost:1313/project-tetra-docs.

    ./serve.sh

  5. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

Useful resources


Last modified September 2, 2020: fix docs to use closing keyword in PR description (#74) (d292a65)