Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
221 lines (140 loc) · 8.81 KB

CONTRIBUTING.md

File metadata and controls

221 lines (140 loc) · 8.81 KB
Raw

Contributing to Berachain Documentation

Thank you for considering contributing. This guide will help you get set up and submit changes.

For environment setup and local tooling commands, use README.md. CONTRIBUTING.md focuses on contribution workflow and review expectations.

Code of Conduct

Berachain has adopted the Contributor Covenant as its Code of Conduct. We expect everyone to follow it. Please read CODE_OF_CONDUCT.md before contributing.

Open Development

All work happens on GitHub. Core team and community contributors both submit pull requests to the same main branch and go through the same review process. We do not use long-lived feature branches; everything targets main.

How to Get in Touch

Reporting Bugs and Suggesting Changes

Issues

We use GitHub Issues for bugs and documentation suggestions. Before opening a new issue, search existing issues to avoid duplicates.

When reporting a problem, please include:

  • What you expected vs what you saw
  • Where in the docs (URL or path) it occurs
  • Your environment if relevant (e.g. browser, OS)

For small fixes (typos, single-sentence clarifications), you can open a PR directly; for larger changes, opening an issue first helps us align before you invest time.

Security

Please do not report security vulnerabilities in public issues. Report them privately (e.g. via Discord to the team or through a private channel the project provides). We’ll acknowledge and work with you on a fix before any public disclosure.

Proposing Larger Changes

If you want to change structure, add a new section, or rework a big part of the docs, we recommend opening an issue first. That way we can agree on the approach before you do a lot of work. For typos and small fixes, a direct PR is fine.

Your First Pull Request

New to open source or to this repo?

  1. Find an open issue (or open one if your idea isn’t listed).
  2. Comment that you’d like to work on it so others don’t duplicate effort.
  3. Follow the Development Workflow below and open a PR.

You can also learn from this free series: How to Contribute to an Open Source Project on GitHub.

Development Workflow

1. Fork and Clone

  • Fork the repo on GitHub: berachain/docs.
  • Clone your fork and add upstream:
git clone https://github.com/YOUR_USERNAME/docs
cd docs
git remote add upstream https://github.com/berachain/docs

Use the setup and local run instructions in README.md.

2. Create a Branch

Work on a branch (do not commit directly to main):

git checkout -b fix/your-change   # or feature/your-feature

3. Add or Edit Content

  • Editing: Open the relevant .mdx file under general/, build/, or reference/ and edit.
  • New page: Create the .mdx file in the right folder, then add it to docs.json (see Adding or moving pages).

Use existing pages as a style reference. Prefer clear, concise language and short paragraphs. Use MDX components where they add value (see Content guidelines).

4. Adding or Moving Pages

Navigation is defined in docs.json under navigation.tabs. Each tab has groups; each group has a group name and a pages array of file paths (without .mdx).

To add a new page:

  1. Create the file, e.g. build/bex/guides/my-new-guide.mdx.
  2. In docs.json, find the right tab and group and add the path to pages:
"pages": [
  "build/bex/guides/pool-creation",
  "build/bex/guides/my-new-guide"
]

To move or rename a page, update both the file path and every reference in docs.json and in other docs (links).

5. Content Guidelines

  • Describe the current system and, where appropriate, future (presented as if current) behavior as of the time of writing. Do not preserve historical narratives, superseded explanations, or framing around past mistakes or obsolete docs in normative pages — update copy to the correct model. Time-ordered deltas belong in changelog-style pages when the repo has them, focused on outcomes of the change, not mechanics.
  • Follow the structure and tone of existing docs.
  • Use US English spelling in prose (color, behavior, favor, labeled).
  • Use Mintlify/MDX components where appropriate, e.g. <Card>, <Steps>, <Note>, <Tip>, <Warning>.
  • Use fenced code blocks with a language tag where you show code.
  • Link to related pages when it helps the reader.
  • Validate your changes locally (see README.md for commands).

6. Validation Before PR

Before opening a PR, run:

mint validate

Also run:

mint broken-links
mint a11y

Run the prose linter on touched files:

brew install vale  # one-time install
make check-vale    # lint the full documentation tree

The full quality gate is make check (validate, broken-links, assets, a11y, vale, redirects, POL address sync). Fix any errors before opening your PR.

When vale flags a project term as misspelled, add it to vale/config/vocabularies/Berachain/accept.txt rather than rephrasing — the file is the single source of truth for terminology vale will accept.

7. Contract Address Source Of Truth

Published POL contract addresses flow through four layers (field names must match exactly):

  1. contracts-internal/script/pol/POLAddresses.sol — struct + per-network literals (mainnet, bepolia)
  2. data/pol-addresses-mapping.json — whether each field is published and its contractsPath
  3. data/contracts.json — addresses shown on the docs site
  4. Generated pages/snippets from make contracts-generate

Do not manually edit generated canonical address pages. After changing data/contracts.json, regenerate:

make contracts-generate

This regenerates:

  • snippets in snippets/contracts/generated/
  • canonical deployed-contract pages in:
    • build/getting-started/deployed-contracts.mdx
    • build/bex/deployed-contracts.mdx
    • build/bend/deployed-contracts.mdx
    • build/bend/deployed-markets.mdx

Check in generated outputs with your data/contracts.json changes in the same PR.

POL address hygiene check

make check-pol-addresses compares POLAddresses.sol, the mapping file, and contracts.json. It prints summary counts (ok, not_ok, not_published) and fails when not_ok > 0. This target is part of make check.

Clone contracts-internal as a sibling of this repo (../contracts-internal) so the verifier can read script/pol/POLAddresses.sol. Without it, make check-pol-addresses skips (other make check steps still run).

make check-pol-addresses              # summary; fails if anything needs action
make list-pol-addresses-not-ok        # list every not_ok row (field, network, reason)

Typical fixes:

  • address_changed or missing_in_contracts_json — update data/contracts.json, then make contracts-generate
  • publish_undecided — add or fix mapping rows (published + contractsPath) or mark published: false when docs should omit the address
  • stale_mapping_field / missing_pol_literal — align struct, literals, and mapping in POLAddresses.sol

Full status taxonomy: header comment in scripts/contracts/verify-pol-addresses.mjs.

At the moment generation and POL sync checks are local Makefile targets (not separate CI jobs), so run them whenever contract data or POLAddresses.sol changes.

8. Commit and Push

  • Commit with a clear message, e.g. Fix typo in BEX swap guide or Add section on pool exits.
  • Keep the scope of each PR focused (one topic or one section is ideal).
git add .
git commit -m "Your message"
git push origin fix/your-change

9. Open a Pull Request

  • Open a PR from your branch to berachain/docs main.
  • Fill in the PR template (description, checklist).
  • If your PR fixes an issue, add “Closes #123” in the description.
  • Allow maintainers to edit your branch (checkbox on the PR).
  • Ensure your fork is up to date with upstream/main before or during review (e.g. git fetch upstream && git merge upstream/main).

Maintainers will review and either merge, request changes, or close with an explanation. We’ll do our best to respond in a timely way.

After Your PR Is Merged

  • You can delete your branch and pull the latest main from upstream.
  • Thank you for contributing; it helps the whole community.

License

By contributing, you agree that your contributions will be licensed under the same MIT License as this project.