Is release-plz the right fit?

[epage]

Tried browsing the docs and I still have a lot of questions. Maybe issues will be created from this but wanted to start with the big picture.

I'm looking for alternative release workflows for a project I'm involved with where cargo-release doesn't quite work because of restricted publish/push permissions.

It involves a large workspace where we have two release workflows

• Product release, controlled by others
• Library release, which we want to control

Implications

• Not everything will be managed by the release tool we use. Tracking as configuration: add a release flag that disables cargo publish, git tag and git release #1020
• Due to project scale, ideally the config is inline, rather than centralized (e.g. using Cargo.toml package.metadata) Tracking as Support package configuration in the package's directory #1022
• Commits may span packages which makes conventional commits ambiguous as to which package the type and breaking status applies to
  • Seems like we'd need a way to control the intended version but the process auto-releases if we manually set the version
• Due to project scale, the person merging the release likely shouldn't be responsible for fine tuning the changelog. Either they waste time taking care of changelog management that should have been done by someone else or they overlook it and merge (the more likely) and provide insufficient quality of changelogs
  • Seems like a changelog fragment system would be needed.
• The person merging the release might not be aware of PRs in the process of being merged (e.g. with bors) which would cause race conditions where changes may go in without awareness within the changelog, version, or the person merging.
• While I prefer "release on every PR", I'm unsure if that will work with all of the libraries we are dealing with and we'd likely need to be able to release subsets as needed.
  • Seems like this could be done today but basically requires a rewrite of the release PR
  • Could go in the opposite direction of a release PR per package and have them blocked if their dependents are unreleased but that might not scale well also

Note: some of these problems exist in our current workflow but that is why I'm looking for something to solve these problems.

[MarcoIeni]

Hi Ed 👋

Not everything will be managed by the release tool we use.

You can have per package configuration, disabling cargo publish, git tag and git releases for the package you don't want to manage with release-plz.

Due to project scale, ideally the config is inline, rather than centralized

At the moment release-plz has a single config file, release-plz.toml. I'm open to add the possibility of configuring release-plz from the Cargo.toml package.metadata. Issue and PR welcome 👍

Commits may span packages which makes conventional commits ambiguous as to which package the type and breaking status applies to

Yeah, that's unfortunate, I also see this when working on release-plz itself. This requires manual editing of the changelog and version before merging the release pr.

Seems like we'd need a way to control the intended version but the process auto-releases if we manually set the version

This will be solved by adding the release-plz set-version command. #704
You add a comment to the PR like release-plz set-version mycrate@1.2.3 and release-plz overrides the version in the release pr.

Due to project scale, the person merging the release likely shouldn't be responsible for fine tuning the changelog.

Mmmh, not sure how to address this. In the workflow I have in mind for release-plz the person who merges the release pr edits the changelog before merging it. Maybe we can add a mechanism so that when merging a code change, you write the exact changelog entry you want in the PR itself or in the commit body. Right now release-plz takes the title of the commit, so it might be too short for a real changelog sometimes.

Seems like a changelog fragment system would be needed.

What do you mean?

The person merging the release might not be aware of PRs in the process of being merged (e.g. with bors) which would cause race conditions

Yeah, that's true! How can we prevent this? 🤔

While I prefer "release on every PR", I'm unsure if that will work with all of the libraries we are dealing with and we'd likely need to be able to release subsets as needed.

We could add a mechanism where we create one release pr for group of packages.

[epage]

btw now I've got an itch about changelog fragments and wrote up some thoughts at epage/epage.github.io#23 (comment) with an eye towards release-plz and would appreciate input.

The idea for the workflow is

• On each PR, a github workflow automatically adds a commit with an inferred changelog. The contributor can then edit it as needed and reviewers can comment on it
• These changelogs can then tell release-plz
  • What packages need a release
  • Whether to bump major, minor, or patch (relative, so major for "0.1.0" is "0.2.0", bumping the absolute major field would require human intervention which seems rare enough to be fine)
  • Whether version requirements need bumping

[MarcoIeni]

I didn't know about the concurrency feature, cool! I opened MarcoIeni/release-plz-action#87

The way to get cargo-release like behavior is if you release on the exact commit the version bump happened on. The release command could "blame" those lines and checkout the most recent commit that changed versions.

This is how release-please (not release-plz) works: release-please does the release on the commit when the PR is merged. For release-plz, I thought it was more clever to release everything always, so that people can manually bump Cargo.toml versions if needed.

I don't understand how releasing on the exact commit when the release PR is merged changes the release itself. If something goes to main before or after the release commit, I think the result is unchanged. Happy to discuss this in a more synchronous way if you think it might help (are you at EuroRust? 😄).

Changelog fragments

The changelog fragments workflow you described is great! Is your intention to create another tool or to integrate this workflow into release-plz?
One thing to keep in mind is that reading the commits from git might not be enough to understand when a crate needs to be released. For example, release-plz distinguishes the commits belonging to each crate and compares the dependencies of Cargo.toml and Cargo.lock to understand if the crate changed.

If your intention is to create a separate tool, I will try to adapt release-plz to add hooks and similar so that you can use it with your tool 👍 We can also split parts of release-plz into crates if you need them for your tool.

a github workflow automatically adds a commit with an inferred changelog

I'm not sure if I like this. It looks very invasive. People would need to run git pull --rebase very often. But this is just personal preference. I think it might be the best approach to solve your issue 👍

[epage]

I don't understand how releasing on the exact commit when the release PR is merged changes the release itself. If something goes to main before or after the release commit, I think the result is unchanged. Happy to discuss this in a more synchronous way if you think it might help (are you at EuroRust? 😄).

Unfortunately, I won't be at EuroRust (really wanted to make it but didn't have as many contacts setup in time to register)

So from my understanding, you can run into this situation:

1. Person A does @bors r+ on PR 20
2. Person B does @bors r+ on PR 21
3. PR 20 is merged into master
4. Person A sees PR 20 is merged and does @bors r+ on the release for PR 20, PR 22
5. PR 21 is merged into master
6. PR 22 is merged into master
7. master's workflow runs that does the publish for PR 22

This means you tag and publish with PR 21 included which will be missing from the changelog, be unreviewed by the release manager, etc.

If your PRs are merged into master with merge-commits, then the commit with the version bump only has ancestors that are strictly those intended to go into that release.

flowchart LR
  pr20(["PR 20 (fix)"])
  pr20_merge["master
  (PR 20 merge commit)"]
  pr21(["PR 21 (breaking change)"])
  pr21_merge["master
  (PR 21 merge commit)"]
  pr22(["PR 22 (release)"])
  pr22_merge["master
  (PR 22 merge commit)"]
  master --> pr20
  master --> pr20_merge
  pr20 --> pr20_merge
  master --> pr21
  pr20_merge --> pr21_merge
  pr21 --> pr21_merge
  pr20_merge --> pr22
  pr22 --> pr22_merge
  pr21_merge --> pr22_merge

The publish happens on "PR 22 merge commit" which includes too much. The idea is to find a way to instead git checkout "PR 22" and do the publish on that.

[epage]

The changelog fragments workflow you described is great! Is your intention to create another tool or to integrate this workflow into release-plz?
One thing to keep in mind is that reading the commits from git might not be enough to understand when a crate needs to be released. For example, release-plz distinguishes the commits belonging to each crate and compares the dependencies of Cargo.toml and Cargo.lock to understand if the crate changed.

If your intention is to create a separate tool, I will try to adapt release-plz to add hooks and similar so that you can use it with your tool 👍 We can also split parts of release-plz into crates if you need them for your tool.

My thought is to release a tool focused only on changelogs which can be integrated into release-plz, much like git-cliff. It would be available as a library and a binary. Then a new action (somewhere) would be published for recording the fragment.

I'm not sure if I like this. It looks very invasive. People would need to run git pull --rebase very often. But this is just personal preference. I think it might be the best approach to solve your issue 👍

I agree that its invasive. I tend to avoid people's commit suggestions in PR reviews because I don't want to pull it.

However,

• New or infrequent contributors will be unaware of the need to run the tool themself. They post a PR and immediately get a failure saying "hey, go run this tool" can feel unsatisfying.
• Installing a tool to contribute might dissuade people from doing so

Maybe it will work great; maybe it won't.

[MarcoIeni]

My thought is to release a tool focused only on changelogs which can be integrated into release-plz, much like git-cliff

I see 👍
It would be best if users could integrate release-plz and this tool easily in the GitHub action, so that release-plz doesn't have this tool as a direct dependency as a library. So again, release-plz should provide hooks and similar. We can also integrate them together in a single github action to make things easier 👍

Maybe it will work great; maybe it won't.

It's definitely worth exploring 👍

Btw, your example on the race condition was very helpful. Thank you for making the time to write it. Now I understand the problem. I created #1030

[epage]

I looked back over my release processes to see if I was missing anything else.

How is a package detected as changed? For a while, cargo release homed things under the most specific Cargo.toml but then switched to cargo publish --list (with some special casing around Cargo.lock) so that I would get he most specific list possible

What happens with dependents when releasing a package

• Does their version req get bumped?
  • Updating causes needless churn but is the safest
  • cargo-release has this configurable
• Do they automatically release?

The rest I'm mentioning for completeness but aren't relevant to this project

I have several projects that need to update the version number or tag in specific places (e.g. docker). This is done with user provided regexes. Tracking as #1024

There are times when specific packages need their version kept in lockstep. For example, in the clap repo, we have clap, clap_builder, and clap_derive that share a version but nothing else. I extended the workspace.package.version support to have the concept of "version groups" (with "workspace" being coupled to workspace.package.version). Tracking as #1023

[MarcoIeni]

How is a package detected as changed?

• The release PR updates packages that are different from the published ones (I do a diff file by file, including Cargo.toml and Cargo.lock dependencies). Here is the ugly loop.
• release-plz release releases all unpublished packages.

cargo publish --list

This would be handy in release-plz, I'm doing this manually basically, but I don't see this option in cargo 🤯

Does their version req get bumped?

Yes, release-plz bumps local dependencies, respecting what parts of the version you specify. E.g. if your dependency goes from 2.3.4 to 2.3.5 and this dependency is specified as 2.3, it's not updated, of course.
We can make it configurable if needed.

[epage]

How is a package detected as changed?

Maybe put a different way: how do you know what package a path belongs to?

cargo package --list

Got this wrong. This lists what files are inside of a package

Yes, release-plz bumps local dependencies, respecting what parts of the version you specify. E.g. if your dependency goes from 2.3.4 to 2.3.5 and this dependency is specified as 2.3, it's not updated, of course.
We can make it configurable if needed.

I'm wondering about using my changelog fragment idea to control this. The idea of the "changesets" model is that you aren't just describing the changelog but the impact of a change on the monorepo.

[MarcoIeni]

Got this wrong. This lists what files are inside of a package

I see. But cargo publish --list to list the packages to be published would be cool to have anyway. 😂 But this would require cargo publish to support workspaces.

how do you know what package a path belongs to?

Oh, I see now. I use the approach you described as "homed things under the most specific Cargo.toml".
But I have an issue to use cargo package --list: #721

I'm wondering about using my changelog fragment idea to control this.

Ok, not very clear how you would do it, but we can try to adapt release-plz to support this. 👍

[epage]

If not aware, rust-lang/cargo#1169 is the relevant issue. I've added it to the cargo roadmap

[epage]

Tracking

• Support package configuration in the package's directory #1022
• Implement release-plz set-version command #704
• configuration: add a release flag that disables cargo publish, git tag and git release #1020
• Allow declaring "version groups" for packages #1023
• Allow updating custom version fields #1024
• Handle race condition on PR merged #1030
• Don't commit excluded files #721

[MarcoIeni]

I also opened

• Consider using concurrency to prevent release-plz running in parallel release-plz-action#87
• Support groups of release PRs #1029

[MarcoIeni]

Cool, hopefully I answered all your questions :)
I marked this discussion as "answered", but feel free to keep discussing here or in new issues/discussions if needed 👍