Skip to content

docs: move release process to RELEASE.md #2196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Aug 26, 2025
Merged

docs: move release process to RELEASE.md #2196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8d75ac7
docs: move release process to RELEASE.md
BigLep Aug 16, 2025
0d820cf
Apply suggestion from @Copilot
BigLep Aug 19, 2025
0d8fb51
Apply suggestion from @Copilot
BigLep Aug 19, 2025
2973730
Apply suggestion from @Copilot
BigLep Aug 19, 2025
3eb0b2f
Apply suggestion from @Copilot
BigLep Aug 19, 2025
7ad1d40
Apply suggestion from @Copilot
BigLep Aug 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 1 addition & 96 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,102 +56,7 @@ If that works, proceed with releasing these crates.

## Releasing

### Release Schedules
The FVM is a workspace of crates which have different release schedules:

* The [primary crates](#primary-crates) are released together.
* The `fvm_ipld_*` crates (living in ipld/) are released independently and only live in this repo for convenience.
* The rest of the crates are for local testing and are not released.

### Versioning
Versioning of the [primary crates](#primary-crates) is not strictly semver compatible:

* Major releases are used to signal when the FVM drops support for old network versions.
* Minor releases are used to signal breaking changes.
* Patch releases are used for bug fixes, new features and other non-breaking changes.

Versioning of the `fvm_ipld_*` crates follows standard semver rules.

### Preparing [Primary Crates](#primary-crates)

To propose a new release, open a pull request with the following changes:

1. Update the version in [`Cargo.toml`](https://github.com/filecoin-project/ref-fvm/blob/master/Cargo.toml): `workspace.package→version`.
2. Update the version of the coupled workspace dependencies in `Cargo.toml` to match the new version
(leaving semver range specifier `~` intact):
1. `wokspace.dependencies→fvm→version`
2. `wokspace.dependencies→fvm_shared→version`
3. `wokspace.dependencies→fvm_sdk→version`
4. `wokspace.dependencies→fvm_integration_tests→version`
3. Update the lockfile with a rebuild: `cargo check --all`.
4. Make sure the `CHANGELOG.md` files in each of `fvm`, `sdk`, and `shared` are all up-to-date (look
through `git log -- path/to/crate`), set the release date & version, and add a new "Unreleased"
section. It may be appropriate to duplicate some entries across these crates if the changes are
relevant to multiple crates.

See [PR #2002](https://github.com/filecoin-project/ref-fvm/pull/2002) for an example.

### Preparing Other/Non-Primary Crates

To propose a release of a crate other than `fvm`, `fvm_shared`, `fvm_sdk`, or
`fvm_integration_tests`, open a pull request with the following changes:

1. Install `cargo-edit` (`cargo install cargo-edit`).
2. 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.
3. Make sure the `CHANGELOG.md` files are all up-to-date (look through `git log -- path/to/crate`),
set the release date & version, and add a new "Unreleased" section.

### Review and Release

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"](https://github.com/orgs/filecoin-project/teams/fvm-crate-owners/members) will:

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

Example steps for an FVM "owner" to release `MINOR` and `PATCH` crates:

1. Merge the `PATCH` release PR to master (e.g., [PR #2030](https://github.com/filecoin-project/ref-fvm/pull/2030)).
2. Publish all [primary crates](#primary-crates) . For each crate (fvm, fvm_shared, fvm_sdk, fvm_integration_tests):

```bash
# Declare an associative array for crate_name → crate_directory
declare -A crates
crates["fvm"]="fvm"
crates["fvm_shared"]="shared"
crates["sdk"]="fvm_sdk"
crates["fvm_integration_tests"]="testing/integration"

workspace_package_version = `tomlq '.workspace.package.version' Cargo.toml`

for crate_name in "${!my_map[@]}"; do
crate_directory = ${crates[$key]}
pushd $crate_directory
cargo publish
git_tag = "$crate_name@v$workspace_package_version"
git tag $git_tag
popd
done
```

3. After creating all tags, push them:

```shell
git push --tags
```

4. Verify the releases on crates.io:
https://crates.io/crates/fvm/versions
https://crates.io/crates/fvm_shared/versions
https://crates.io/crates/fvm_sdk/versions
https://crates.io/crates/fvm_integration_tests/versions
See [RELEASE.md](RELEASE.md) for detailed release instructions.

[chat]: https://docs.filecoin.io/about-filecoin/chat-and-discussion-forums/#chat
[discuss]: https://github.com/filecoin-project/fvm-specs/discussions
Expand Down
110 changes: 110 additions & 0 deletions RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
# Releasing

## Release Schedules
The FVM is a workspace of crates which have different release schedules:

* The [primary crates](#primary-crates) are released together.
* The `fvm_ipld_*` crates (living in ipld/) are released independently and only live in this repo for convenience.
* The rest of the crates are for local testing and are not released.

## Primary Crates
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).

## Versioning
Versioning of the [primary crates](#primary-crates) is not strictly semver compatible:

* Major releases are used to signal when the FVM drops support for old network versions.
* Minor releases are used to signal breaking changes.
* Patch releases are used for bug fixes, new features and other non-breaking changes.

Versioning of the `fvm_ipld_*` crates follows standard semver rules.

## Preparing [Primary Crates](#primary-crates)

To propose a new release, open a pull request with the following changes:

1. Update the version in [`Cargo.toml`](https://github.com/filecoin-project/ref-fvm/blob/master/Cargo.toml): `workspace.package→version`.
2. Update the version of the coupled workspace dependencies in `Cargo.toml` to match the new version
(leaving semver range specifier `~` intact):
1. `workspace.dependencies→fvm→version`
2. `wokspace.dependencies→fvm_shared→version`
3. `wokspace.dependencies→fvm_sdk→version`
1. `workspace.dependencies→fvm→version`
2. `workspace.dependencies→fvm_shared→version`
3. `workspace.dependencies→fvm_sdk→version`
4. `workspace.dependencies→fvm_integration_tests→version`
3. Update the lockfile with a rebuild: `cargo check --all`.
4. Make sure the `CHANGELOG.md` files in each of `fvm`, `sdk`, and `shared` are all up-to-date (look
through `git log -- path/to/crate`), set the release date & version, and add a new "Unreleased"
section. It may be appropriate to duplicate some entries across these crates if the changes are
relevant to multiple crates.

See [PR #2002](https://github.com/filecoin-project/ref-fvm/pull/2002) for an example.

## Preparing Other/Non-Primary Crates

To propose a release of a crate other than `fvm`, `fvm_shared`, `fvm_sdk`, or
`fvm_integration_tests`, open a pull request with the following changes:

1. Install `cargo-edit` (`cargo install cargo-edit`).
2. 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.
3. Make sure the `CHANGELOG.md` files are all up-to-date (look through `git log -- path/to/crate`),
set the release date & version, and add a new "Unreleased" section.

## Review and Release

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"](https://github.com/orgs/filecoin-project/teams/fvm-crate-owners/members) will:

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

Example steps for an FVM "owner" to release `MINOR` and `PATCH` crates:

1. Merge the `PATCH` release PR to master (e.g., [PR #2030](https://github.com/filecoin-project/ref-fvm/pull/2030)).
2. Publish all [primary crates](#primary-crates) . For each crate (fvm, fvm_shared, fvm_sdk, fvm_integration_tests):

```bash
# Declare an associative array for crate_name → crate_directory
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can't help but feel this is a bit much, and just a list of 8 commands you modify and run would do the job; but I guess this illustrates it 🤷

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair. This is just moving ower what was previously in CONTRIBUTING.md. For now I think we keep it knowing this is all about to get stripped down soon once we have better automation in place

declare -A crates
crates["fvm"]="fvm"
crates["fvm_shared"]="shared"
crates["fvm_sdk"]="fvm_sdk"
crates["fvm_integration_tests"]="testing/integration"

workspace_package_version = `tomlq '.workspace.package.version' Cargo.toml`

for crate_name in "${!crates[@]}"; do
crate_directory = ${crates[$key]}
pushd $crate_directory
cargo publish
workspace_package_version=`tomlq '.workspace.package.version' Cargo.toml`

for crate_name in "${!my_map[@]}"; do
crate_directory=${crates[$key]}
pushd $crate_directory
cargo publish
git_tag="$crate_name@v$workspace_package_version"
git tag $git_tag
popd
done
```

3. After creating all tags, push them:

```shell
git push --tags
```

4. Verify the releases on crates.io:
https://crates.io/crates/fvm/versions
https://crates.io/crates/fvm_shared/versions
https://crates.io/crates/fvm_sdk/versions
https://crates.io/crates/fvm_integration_tests/versions
55 changes: 0 additions & 55 deletions doc/testnet-release-process.md
View file
Open in desktop

This file was deleted.

30 changes: 0 additions & 30 deletions doc/workspace.dot
View file
Open in desktop

This file was deleted.

Binary file removed doc/workspace.png
View file
Open in desktop
Binary file not shown.
Loading