CONTRIBUTING.md

Contributing

This document describes the process of contributing to the reference FVM implementation (this project).

Issues

If you have a general FVM related question or idea, please either as on the Filecoin Slack, or open a new discussion in fvm-specs.

If you'd like to report a bug or suggest an enhancement in the reference FVM implementation, please file an issue.

Pull Requests

To make a change to the FVM.

1. When in doubt, open an issue first to discuss the change.
2. Make your change.
3. Write a test for your change.
4. Update the crate's CHANGELOG.md. If you're making any breaking changes, prefix change with "BREAKING:".
5. Finally, open a PR.

Releasing

To prepare a release.

1. Make sure the crate's CHANGELOG.md is up-to-date (look through git log -- path/to/crate).
2. Make sure the changes are well tested. See [builtin actors testing][builtin actors testing].
3. Pick a next version (for each crate you're releasing). Look through the changelogs and carefully decide if it's a breaking release or not. Then read rust's semver documentation.
4. Install cargo-edit (cargo install cargo-edit).
5. Create a new branch.
6. Use cargo set-version to set the version for each crate you're releasing. This will both update the crate version, and make all other crates in the workspace depend on the latest version.
7. Make sure the changelogs are all up-to-date, set the release date & version, and add a new "Unreleased" section.
8. Commit your changes, and make a PR.

Once the release is prepared, it'll go through a review:

1. Make sure that we're ready to release. E.g., make sure downstream can consume the release.
2. Make sure that we're correctly following semver.
3. Make sure that we're not missing anything in the changelogs.

Finally, an FVM "owner" will:

1. Merge the release PR to master.
2. For each released crate, create a git: crate_name@crate_version.
3. Run cargo publish for each released crate (in dependency order).

Crate Dependency Graph

The crates in this workspace have the following structure:

Builtin-Actors Testing

If you're releasing any non-trivial changes to crates used by the builtin actors, please test them. This includes:

• Any crates in ipld/ except car.
• shared/ (fvm_shared).
• sdk/ (fvm_sdk).

To test:

1. Checkout this repo as ref-fvm/ and and the builtin-actors repo as builtin-actors/ in the same directory.
2. Uncomment the "patch" section in builtin-actors/Cargo.toml that starts with:

   [patch.crates-io]
   fvm_shared = { path = "../ref-fvm/shared" }
   ...

3. Run cargo test --all (or, at a minimum, cargo check --all --tests --lib.

If that works, proceed with releasing these crates.