Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The following guidelines explain how to contribute to the Besu documentation repository.

Your first contribution

Start by 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, assign it to yourself, or message us on the Besu Discord and we’ll assign it to you.

Contribution workflow

The Besu documentation uses a docs-as-code approach, meaning documentation is created using the same tools as code. The contribution workflow involves proposing changes to the docs by creating forks and pull requests (PRs) on the documentation GitHub repository. This facilitates open contributions, testing, and documentation is maintained using a "contributor workflow" where everyone without exception contributes proposed changes using "pull-requests" (PRs).This facilitates social contribution, easy testing, and peer review.

To contribute changes, use the following workflow:

  1. Fork the Besu documentation repository.

  2. Clone your fork to your computer.

    • git clone <FORKED-REPO>
    • cd besu-docs
  3. Add an upstream remote.

    • git remote add upstream <ORIGINAL-REPO>
  4. Create and checkout a topic branch

    and name

    , naming it appropriately.

    Starting the branch name with the

    We recommend using the issue number and short description, which is a

    good practice and a

    reminder to fix only one issue in a

    Pull-Request (PR)._
  5. Make your changes adhering to the documentation conventions described below. In general a commit serves a single purpose and diffs should be easily comprehensible. For this reason do not mix any formatting fixes or typo fixes with actual documentation changes.
  6. Commit your changes  see How to Write a Git Commit Message article by Chris Beams.
  7. Test your changes locally before pushing to ensure that what you are proposing is not breaking another part of the doc.
  8. PR. For example, 183-doc-cli-option.

    • git checkout -b <ISSUE-NUM>-<ISSUE-DESC>
  9. Open the Besu documentation repository in a text editor of your choice (for example, VS Code) and make your changes to the documentation content located in the /docs  folder. Make sure to follow the style guidelines and format your Markdown correctly. If you delete, rename, or move a documentation file, make sure to add a redirect.

  10. Preview your changes locally to check that the changes render correctly. Make sure you switch to the development version of the docs in the preview.

  11. Add and commit your changes, using a clear commit message. Make sure to add a DCO message to each commit. Push

    Push

    your changes to your remote fork (usually

    labeled as

    named origin).

  12. Create a pull-request (PR) on the Besu doc repository. If the PR addresses an existing issue, include the issue number in the PR title in square brackets (for example, [BESU-1234]).
  13. Add labels to identify the type of your PR. For example, if your PR fixes a bug, add the "bug" label.
  14. If the PR addresses an existing issue, comment in the issue with the PR number.
  15. Ensure your changes are reviewed. Select the reviewers you would like to review your PR. If you don't know who to choose, simply select the reviewers proposed by GitHub or leave blank and let us know on Hyperledger Besu chat.
  16. Make any required changes on your contribution from the reviewers feedback. Make the changes, commit to your branch, and push to your remote fork.
    • git add *
    • git commit -m "<COMMIT-MESSAGE>"
    • git push origin
  17. Navigate to the original Besu 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>
  18. The bottom of the PR page displays a list of checks that verify links, Markdown syntax, and more. If you have any errors, make any required changes to your PR, repeating steps 5-7. If you want to include a new word that causes a spell check error, you can add that word to the project-words.txt file.

  19. In the right sidebar of your PR, select the reviewer(s) who should review your PR (typically the original issue raiser). 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.

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

  21. After your PR is validated, all checks have passed,

    When your PR is validated, all tests passed

    and your branch has no conflicts with the target branch, you can

    "squash and merge" your PR and you're done. You contributed to Hyperledger Besu documentation! Thanks !

    merge your PR. You can delete the topic branch after merging your PR.

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

Note: The Besu documentation repository default branch is now named main.