|
| 1 | +# Releasing |
| 2 | + |
| 3 | +## Release Schedules |
| 4 | +The FVM is a workspace of crates which have different release schedules: |
| 5 | + |
| 6 | +* The [primary crates](#primary-crates) are released together. |
| 7 | +* The `fvm_ipld_*` crates (living in ipld/) are released independently and only live in this repo for convenience. |
| 8 | +* The rest of the crates are for local testing and are not released. |
| 9 | + |
| 10 | +## Primary Crates |
| 11 | +The primary crates are `fvm`, `fvm_shared`, `fvm_sdk`, and the integration testing framework `fvm_integration_tests`. These are the crates that have [`version.workspace = true`](https://github.com/search?q=repo%3Afilecoin-project%2Fref-fvm%20version.workspace%20%3D%20true&type=code). |
| 12 | + |
| 13 | +## Versioning |
| 14 | +Versioning of the [primary crates](#primary-crates) is not strictly semver compatible: |
| 15 | + |
| 16 | +* Major releases are used to signal when the FVM drops support for old network versions. |
| 17 | +* Minor releases are used to signal breaking changes. |
| 18 | +* Patch releases are used for bug fixes, new features and other non-breaking changes. |
| 19 | + |
| 20 | +Versioning of the `fvm_ipld_*` crates follows standard semver rules. |
| 21 | + |
| 22 | +## Preparing [Primary Crates](#primary-crates) |
| 23 | + |
| 24 | +To propose a new release, open a pull request with the following changes: |
| 25 | + |
| 26 | +1. Update the version in [`Cargo.toml`](https://github.com/filecoin-project/ref-fvm/blob/master/Cargo.toml): `workspace.package→version`. |
| 27 | +2. Update the version of the coupled workspace dependencies in `Cargo.toml` to match the new version |
| 28 | + (leaving semver range specifier `~` intact): |
| 29 | + 1. `workspace.dependencies→fvm→version` |
| 30 | + 2. `wokspace.dependencies→fvm_shared→version` |
| 31 | + 3. `wokspace.dependencies→fvm_sdk→version` |
| 32 | + 1. `workspace.dependencies→fvm→version` |
| 33 | + 2. `workspace.dependencies→fvm_shared→version` |
| 34 | + 3. `workspace.dependencies→fvm_sdk→version` |
| 35 | + 4. `workspace.dependencies→fvm_integration_tests→version` |
| 36 | +3. Update the lockfile with a rebuild: `cargo check --all`. |
| 37 | +4. Make sure the `CHANGELOG.md` files in each of `fvm`, `sdk`, and `shared` are all up-to-date (look |
| 38 | + through `git log -- path/to/crate`), set the release date & version, and add a new "Unreleased" |
| 39 | + section. It may be appropriate to duplicate some entries across these crates if the changes are |
| 40 | + relevant to multiple crates. |
| 41 | + |
| 42 | +See [PR #2002](https://github.com/filecoin-project/ref-fvm/pull/2002) for an example. |
| 43 | + |
| 44 | +## Preparing Other/Non-Primary Crates |
| 45 | + |
| 46 | +To propose a release of a crate other than `fvm`, `fvm_shared`, `fvm_sdk`, or |
| 47 | +`fvm_integration_tests`, open a pull request with the following changes: |
| 48 | + |
| 49 | +1. Install `cargo-edit` (`cargo install cargo-edit`). |
| 50 | +2. Use `cargo set-version` to set the version for each crate you're releasing. This will both |
| 51 | + update the crate version, and make all other crates in the workspace depend on the latest version. |
| 52 | +3. Make sure the `CHANGELOG.md` files are all up-to-date (look through `git log -- path/to/crate`), |
| 53 | + set the release date & version, and add a new "Unreleased" section. |
| 54 | + |
| 55 | +## Review and Release |
| 56 | + |
| 57 | +Once the release is prepared, it'll go through a review: |
| 58 | + |
| 59 | +1. Make sure that we're _ready_ to release. E.g., make sure downstream can consume the release. |
| 60 | +2. Make sure that we're correctly following semver. |
| 61 | +3. Make sure that we're not missing anything in the changelogs. |
| 62 | + |
| 63 | +Finally, an [FVM "owner"](https://github.com/orgs/filecoin-project/teams/fvm-crate-owners/members) will: |
| 64 | + |
| 65 | +1. Merge the release PR to master. |
| 66 | +2. For each released crate, create a git tag: `crate_name@crate_version`. |
| 67 | +3. Run `cargo publish` for each released crate (in dependency order). |
| 68 | + |
| 69 | +Example steps for an FVM "owner" to release `MINOR` and `PATCH` crates: |
| 70 | + |
| 71 | +1. Merge the `PATCH` release PR to master (e.g., [PR #2030](https://github.com/filecoin-project/ref-fvm/pull/2030)). |
| 72 | +2. Publish all [primary crates](#primary-crates) . For each crate (fvm, fvm_shared, fvm_sdk, fvm_integration_tests): |
| 73 | + |
| 74 | +```bash |
| 75 | +# Declare an associative array for crate_name → crate_directory |
| 76 | +declare -A crates |
| 77 | +crates["fvm"]="fvm" |
| 78 | +crates["fvm_shared"]="shared" |
| 79 | +crates["fvm_sdk"]="fvm_sdk" |
| 80 | +crates["fvm_integration_tests"]="testing/integration" |
| 81 | + |
| 82 | +workspace_package_version = `tomlq '.workspace.package.version' Cargo.toml` |
| 83 | + |
| 84 | +for crate_name in "${!crates[@]}"; do |
| 85 | + crate_directory = ${crates[$key]} |
| 86 | + pushd $crate_directory |
| 87 | + cargo publish |
| 88 | +workspace_package_version=`tomlq '.workspace.package.version' Cargo.toml` |
| 89 | + |
| 90 | +for crate_name in "${!my_map[@]}"; do |
| 91 | + crate_directory=${crates[$key]} |
| 92 | + pushd $crate_directory |
| 93 | + cargo publish |
| 94 | + git_tag="$crate_name@v$workspace_package_version" |
| 95 | + git tag $git_tag |
| 96 | + popd |
| 97 | +done |
| 98 | +``` |
| 99 | +
|
| 100 | +3. After creating all tags, push them: |
| 101 | +
|
| 102 | +```shell |
| 103 | +git push --tags |
| 104 | +``` |
| 105 | +
|
| 106 | +4. Verify the releases on crates.io: |
| 107 | + https://crates.io/crates/fvm/versions |
| 108 | + https://crates.io/crates/fvm_shared/versions |
| 109 | + https://crates.io/crates/fvm_sdk/versions |
| 110 | + https://crates.io/crates/fvm_integration_tests/versions |
0 commit comments