Skip to content
This repository has been archived by the owner on Aug 19, 2024. It is now read-only.

Contributing to documentation

Jump to bottom
Alexandra Tran edited this page Feb 15, 2022 · 14 revisions

The following guidelines explain how to contribute to this repository and the other ConsenSys documentation repositories.

Table of contents

List of ConsenSys documentation repositories

The following are the public ConsenSys documentation repositories that use this common repository. Use this guide to contribute to this repository or any of these repositories:

The following are the private ConsenSys documentation repositories that use this common repository:

Your first contribution

Start by choosing a documentation repository and looking for issues that have a Good First Issue label. Good First Issues might require only a few lines of documentation, or have enough information for a newcomer to easily document.

When you've identified an issue you want to work on, message us on that project's channel on Discord, and we'll assign it to you.

Contribution workflow

The documentation contribution workflow consists of forking repositories and submitting pull requests (PRs). This facilitates social contribution, easy testing, and peer review.

To contribute changes:

  1. Fork the documentation repository in which you want to make a change.

  2. Clone your fork to your computer with the --recursive option to retrieve this common submodule.

    git clone --recursive <FORKED-REPO>

  3. Add an upstream remote.

    git remote add upstream <ORIGINAL-REPO>

  4. Create and checkout a topic branch, naming it appropriately. We recommend using the issue number and short description, which is a reminder to fix only one issue in a PR. For example, 183-doc-cli-option.

    git checkout -b <ISSUE-NUM>-<ISSUE-DESC>

  5. Open the documentation repository in a text editor of your choice, for example IntelliJ, and make your changes. Refer to the documentation style guide and the MkDocs and Markdown guide when making documentation changes.

  6. Preview your changes with MkDocs to check that the changes render correctly.

  7. Add and commit your changes, using a clear commit message. Push your changes to your remote fork (usually named origin).

    git add *
git commit -m "<COMMIT-MESSAGE>"
git push origin

  8. Navigate to the original ConsenSys documentation repository, and you'll see a banner prompting you to create a PR with your recent changes. Create a PR, filling out the description according to the template. Remember to link the issue that the PR fixes in the description.

    fixes #<ISSUE-NUM>

  9. The bottom of the PR page displays a list of CircleCI checks that verify links, Markdown syntax, writing style, and more. If you have any CI errors, make any required changes to your PR, repeating steps 5-7.

  10. In the right sidebar of your PR, select the reviewer(s) who should review your PR (typically the original issue raiser). Ask the ConsenSys documentation team to review by selecting ConsenSys/protocol-pliny as a reviewer. If you don't know who to choose or can't because you're not a maintainer yet, select the reviewers listed by GitHub or keep the default value.

  11. Make any required changes to your PR based on reviewer feedback, repeating steps 5-7.

  12. After your PR is validated, all checks have passed, and your branch has no conflicts with the target branch, you can merge your PR.

Tip: You can use a Git client such as Fork instead of the command line.

Common submodule

Every listed ConsenSys documentation repository includes this common repository as a Git submodule. This repository contains templates and scripts used by each documentation repository, and is a single place to update.

Apart from the usual license and README files at the root of the repository, this repository includes:

  • build_tools directory - Contains all the CircleCI-related scripts and configuration files used to verify links, Markdown syntax, writing style, and more.
    • scripts subdirectory - Contains shortcut scripts to run the CI jobs locally to test your changes.
    • package.json and package-lock.json - Files that must be in the documentation project root. The real files are in the common repository and symbolic links point to them from the documentation project root.
  • custom_theme directory - Contains the MkDocs custom HTML templates, CSS and JS scripts, and images for the ConsenSys documentation custom design.

Retrieve the submodule

When you clone a ConsenSys documentation repository, use the --recursive option to retrieve the submodule.

git clone --recursive <FORKED-REPO>

If you didn't use the --recursive option when first cloning the repository, or if you removed the common submodule directory and links, you can fix this and update your local repository by running git submodule update --init.

Update repositories to the latest submodule version

When someone updates the code files in this common repository, you must update any forked documentation repositories to the latest common submodule version in order to incorporate the common changes into your repository. You can do this by running the following commands in your project's root directory:

cd common
git checkout master && git pull
cd ..
git add common
git commit -m "updating submodule to latest"

Code of conduct

This project and everyone participating in it is governed by the contributor covenant code of conduct. By contributing to documentation, you're expected to uphold this code. Please report unacceptable behavior to private-quorum@consensys.net.

Contributor License Agreement

When you submit a PR for your first contribution to a documentation repository, you must read and sign the ConsenSys Individual Contributor License Agreement (CLA) when prompted before you can merge the PR.

Table of contents

Clone this wiki locally