Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (76 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

118 lines (76 loc) · 5.64 KB
Raw

Contributing

Thank you for your interest in contributing to Celestia-Node!

All work on the code base should be motivated by our Github issues. If you would like to work on an issue which already exists, please indicate so by leaving a comment.

All new contributions should start with a Github issue. The issue helps capture the problem you're trying to solve and allows for early feedback. Once the issue is created the process can proceed in different directions depending on how well-defined the problem and potential solution are. If the change is simple and well understood, maintainers will indicate their support with a heartfelt emoji.

When the problem is well understood but the solution leads to large structural changes to the code base, these changes should be proposed in the form of an Architectural Decision Record (ADR). The ADR will help build consensus on an overall strategy to ensure the code base maintains coherence in the larger context. If you are not comfortable with writing an ADR, you can open a less-formal issue and the maintainers will help you turn it into an ADR.

How to pick a number for the ADR?

Find the largest existing ADR number and bump it by 1.

Each stage of the process is aimed at creating feedback cycles which align contributors and maintainers to make sure:

  • Contributors don’t waste their time implementing/proposing features which won’t land in master.
  • Maintainers have the necessary context in order to support and review contributions.

PR Naming

PR titles follow conventional commits and the subject must start with exactly one review level tag:

type(pkg): [level] concise title

Example:

fix(service/header): [medium] remove race in core_listener

Use ! for breaking changes (e.g. feat(nodebuilder)!: [high] rename config field). Include the same tag in the PR description with a brief reason, e.g. Review level: [low] — documentation only.

  • [high]: Deep review for consensus, state transitions, security, or other changes with significant risk. Examples: DAS/availability verification, shrex/p2p protocol changes, header verification, fraud proofs, state/tx submission, breaking API/config changes.
  • [medium]: Standard review for code changes with limited impact and well-understood behavior.
  • [low]: Focused review for straightforward docs, tests, or tooling changes with low risk.

Choose the higher level when unsure. A small diff can still need deep review. CI checks the title format; reviewers should confirm the chosen level. Dependabot titles default to [medium]; maintainers should confirm the level.

Branching Model and Release

The main development branch is main.

Every release is maintained in a release branch named vX.Y. On each respective release branch, we tag the releases vX.Y.0, vX.Y.1 and so forth.

Note all pull requests should be squash merged except for merging to a release branch (named vX.Y). This keeps the commit history clean and makes it easy to reference the pull request where a change was introduced.

Development Procedure

The latest state of development is on main, which must never fail make test. Never force push main.

To begin contributing, create a development branch on your fork.

Make changes, and before submitting a pull request, update the CHANGELOG_PENDING.md to record your change. Also, git rebase on top of the latest main.

Sometimes (often!) pull requests get out-of-date with main, as other people merge different pull requests to main. It is our convention that pull request authors are responsible for updating their branches with main. (This also means that you shouldn't update someone else's branch for them; even if it seems like you're doing them a favor, you may be interfering with their git flow in some way!)

Merging Pull Requests

It is also our convention that authors merge their own pull requests, when possible. External contributors may not have the necessary permissions to do this, in which case, a member of the core team will merge the pull request once it's been approved.

Before merging a pull request:

  • Ensure pull branch is up-to-date with a recent main (GitHub won't let you merge without this!)
  • Run make test to ensure that all tests pass
  • Ensure that all other CI checks pass / are green
  • Squash merge pull request

Git Commit Style

Commits follow conventional commits with the package as the scope, and a description that finishes the sentence "This change modifies Celestia-Node to...". For example,

fix(cmd/debug): execute p.Signal only when p is not nil

[potentially longer description in the body]

Fixes #nnnn

The squashed commit on main uses the PR title, so it carries the review level tag (see PR Naming).

Each PR should have one commit once it lands on main; this can be accomplished by using the "squash and merge" button on Github. Be sure to edit your commit message, though!

Testing

Unit tests

Unit tests are located in _test.go files as directed by the Go testing package. If you're adding or removing a function, please check there's a TestType_Method test for it.

Run: make test

Protobuf

If your PR modifies *.proto files, you will need to regenerate protobuf files with make pb-gen. Note this command assumes you have installed protoc.