Skip to content

Latest commit

 

History

History
87 lines (63 loc) · 7.16 KB

CONTRIBUTING.md

File metadata and controls

87 lines (63 loc) · 7.16 KB
Raw

Contributing to Lotus

Lotus is a universally open project and welcomes contributions of all kinds: code, docs, and more. We appreciate your interest in contributing!

Before Contributing

  1. Familiarize yourself with our release flow to understand how changes are incorporated into releases. This includes our branch strategy and where to target PRs.
  2. If the proposal entails a protocol change, please first submit a Filecoin Improvement Proposal.
  3. If the change is complex and requires prior discussion, open an issue or a discussion to request feedback before you start working on a pull request. This is to avoid disappointment and sunk costs, in case the change is not actually needed or accepted.
  4. Please refrain from submitting PRs to adapt existing code to subjective preferences. The changeset should contain functional or technical improvements/enhancements, bug fixes, new features, or some other clear material contribution. Simple stylistic changes are likely to be rejected in order to reduce code churn.

Implementing Changes

When implementing a change:

  1. Adhere to the standard Go formatting guidelines, e.g. Effective Go. Run go fmt.
  2. Stick to the idioms and patterns used in the codebase. Familiar-looking code has a higher chance of being accepted than eerie code. Pay attention to commonly used variable and parameter names, avoidance of naked returns, error handling patterns, etc.
  3. Comments: follow the advice on the Commentary section of Effective Go.
  4. Minimize code churn. Modify only what is strictly necessary. Well-encapsulated changesets will get a quicker response from maintainers.
  5. Lint your code with golangci-lint (CI will reject your PR if unlinted).
  6. Add tests.
  7. Write clean, thoughtful, and detailed commit messages. This is even more important than the PR description, because commit messages are stored inside the Git history. One good rule is: if you are happy posting the commit message as the PR description, then it's a good commit message.

Working with builtin-actors

For doing FIP development that involves a change in builtin-actors which needs to also be exposed in Lotus, see the builtin-actor Development Guide.

PR Title Conventions

PR titles should follow Conventional Commits standard. This means the PR title should be in the form of <type>(<scope>): <description>

  • example: fix(mempool): introduce a cache for valid signatures
  • type: MUST be one of build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test
  • scope: OPTIONAL arbitrary string that is usually one of api, chain, deps, mempool, multisig, networking, paych, proving, sealing, state, wallet
  • Breaking changes must add a !
  • Optionally the PR title can be prefixed with [skip changelog] if no changelog edits should be made for this change.

Note that this is enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/pr-title-check.yml

CHANGELOG Management

To expedite the release process, the CHANGELOG is built-up incrementally. We enforce that each PR updates CHANGELOG.md or signals that the change doesn't need it. If the PR affects users (e.g., new feature, bug fix, system requirements change), update the CHANGELOG.md and add details to the UNRELEASED section. If the change does not require a CHANGELOG.md entry, do one of the following:

  • Add [skip changelog] to the PR title
  • Add the label skip/changelog to the PR

Note that this is enforced with https://github.com/filecoin-project/lotus/blob/master/.github/workflows/changelog.yml

Dependency Management

We strive to use release dependencies because:

  1. Security / reliability - While there's no guarantee that a released version doesn't have bugs or issues, it seems fair to assume that non-released versions have even more. For example, #12467 was triggered because of a bug in non-released library that lotus was depending on when the latest released version didn't have the bug.
  2. Faster builds
  3. Makes Lotus a better citizen when it's imported by other projects.

We enforce that each dependency on an unreleased version of a package is explicitly documented in the go.mod file via an inline comment of the form dependency-check-ignore: <reason>.

Markdown Conventions

We optimize our markdown files for viewing on GitHub. That isn't to say other syntaxes can't be used, but that is the flavor we focus on and at the minimum don't want to break.

Table Of Contents

For longer documents, we tend to inline a table of contents (TOC). This is slightly annoying with Markdown on GitHub because the actual table of contents needs to be checked-in rather than just giving a directive to the renderer like [][[_TOC_]] on GitLab](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents). (Yes GitHub UI does enable someone to see an auto-generated outline if they click the "outline" button on the top right-hand corner when viewing a Markdown file, but that isn't necessarily obvious to users, requires an extra click, and doesn't enable any customization.)

There is tooling that can help with auto-generating and updating a TOC and allow customization. Maintainers aren't wedded to a particular format/standard/tool but have gone with VS Code Markdown All in One because it has what we needed and is the most popular VS Code plugin for this functionality (at least as of 202408).

Getting Help

If you need help with your contribution, please don't hesitate to ask questions in our discussions or reach out to the maintainers.

Thank you for contributing to Lotus!