-
Notifications
You must be signed in to change notification settings - Fork 13
Contributing to documentation
The following guidelines explain how to contribute to this repository and the other ConsenSys documentation repositories.
- List of ConsenSys documentation repositories
- Your first contribution
- Contribution workflow
- Common submodule
- Code of conduct
- Contributor License Agreement
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:
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.
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:
-
Fork the documentation repository in which you want to make a change.
-
Clone your fork to your computer with the
--recursive
option to retrieve this common submodule.git clone --recursive <FORKED-REPO>
-
git remote add upstream <ORIGINAL-REPO>
-
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>
-
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.
-
Preview your changes with MkDocs to check that the changes render correctly.
-
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
-
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>
-
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.
-
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.
-
Make any required changes to your PR based on reviewer feedback, repeating steps 5-7.
-
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.
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
andpackage-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.
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
.
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"
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.
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.