Simplification of the release process

[ThetaSinner]

Choosing what to release:

• Not every change that is made in crates that sit below the HDI/HDK should result in a release for these crates. We want to choose when we release these and that probably means we should have them outside the monorepo. However, we use these in tests, so that needs more thought.
• Only releasing changed crates makes changing versions complex. For example, if we deliberately bump the minor version but only release changed crates then we end up with a mix of 0.X+1.0 and 0.X.Y.dev.Z. Then what should happen next? Well its clear to a person that we want the X in 0.X.Y.dev.Z to become X+1 next time that crate changes. However, automating this logic is deeply complex. We haven't currently implemented this and some crates get stuck on the wrong version, requiring manual intervention to move them forwards.

Automating semver:

• This is a really hard problem and is always ultimately a human decision. We have an imperative system for doing this that is masquerading as a declarative system. We have to make source changes to our CHANGELOGs to tell the release-automation what to do. We've then gone and made a script that sets them all to the same value, because that's what we actually do. It is then a stateful problem to understand what will actually happen on the next release because the crates are actually being versioned independently and any inconsistency introduced into a CHANGELOG can result in some crates releasing at a different version. Because this is permitted by the system, the release-automation cannot decide whether that was intentional or not.
• We use multiple inputs to make decisions which are the previous releases on crates.io, tags on the repo and the CHANGELOGs. If any of these change, it is not clear to me exactly what the behaviour should be. The intention was to ensure consistency but in reality, these can also affect the outcomes in hard to predict ways. How should the tool decide what to do if one of these three things already exists? Well the result is different for a version existing in the changelog vs crates.io. So you have to really understand what the tool will do.

---

Instead I think we want something simpler that rougly fits these requirements:

• Choosing what version should be released needs to be a human decision. The release can be kicked off by tagging the repository with a given version. E.g. "git tag -a v0.5.0-dev.1 && git push origin v0.5.0-dev.1".
• We have a way to restart the release for a given version and it will release only the crates that aren't found on crates.io.
• Anything that needs to be versioned out of lockstep is moved out of the monorepo.
• The release process can be easily tested locally without tags and commits being created that have to be tidied up. I know that some of this can be disabled currently but we don't have docs showing how so you have to figure it out each time. If we need flags then we need a documented check process.

[steveej]

i understand this effort stems from the hiccup with the most recent branch split and i welcome simplification to lessen the chances of repeating that. on a related note, i recently opened #3629 to explore other options which might suffice our needs so #3464 becomes a less heavy lift.

i'd like to fill in some of my understanding of the current system as i think we can use it a bit longer and we don't need to rush to a new one immediately.

---

• Not every change that is made in crates that sit below the HDI/HDK should result in a release for these crates. We want to choose when we release these and that probably means we should have them outside the monorepo.

there is a boolean (unreleasable) that can be added to the crate's CHANGELOG frontmatter to prevent any given crate (and all its dependents) to be released. the use-case you describe is exactly what i had in mind for this feature, we just haven't made use of it so far. here's a test for the feature.

• Only releasing changed crates makes changing versions complex. For example, if we deliberately bump the minor version but only release changed crates then we end up with a mix of 0.X+1.0 and 0.X.Y.dev.Z. Then what should happen next? Well its clear to a person that we want the X in 0.X.Y.dev.Z to become X+1 next time that crate changes. However, automating this logic is deeply complex. We haven't currently implemented this and some crates get stuck on the wrong version, requiring manual intervention to move them forwards.

if the CHANGELOGs are adjusted to signal a minor bump this alone will cause otherwise unchanged crates to be regarded as changed and also be released. so from how i understand your requirement here we've already implemented this. IIUC combined with the unreleasable feature we've already got an implementation of the logic you describe.

• This is a really hard problem and is always ultimately a human decision. We have an imperative system for doing this that is masquerading as a declarative system.

on a meta note, all declarative data structures are ultimately imperatively processed.

We have to make source changes to our CHANGELOGs to tell the release-automation what to do. We've then gone and made a script that sets them all to the same value, because that's what we actually do. It is then a stateful problem to understand what will actually happen on the next release because the crates are actually being versioned independently and any inconsistency introduced into a CHANGELOG can result in some crates releasing at a different version. Because this is permitted by the system, the release-automation cannot decide whether that was intentional or not.

i can see that the statefulness is the least intuitive part of the system, also in that the processing will change the CHANGELOG attributes back to their (implicit) default if they diverge from that. we haven't been making much use of that feature either. e.g. i foresaw that we set default_unreleasable: true on the HDI to always have to explicitly allow releasing it by setting unreleasable: false.

We use multiple inputs to make decisions which are the previous releases on crates.io, tags on the repo and the CHANGELOGs. If any of these change, it is not clear to me exactly what the behaviour should be. The intention was to ensure consistency but in reality, these can also affect the outcomes in hard to predict ways. How should the tool decide what to do if one of these three things already exists? Well the result is different for a version existing in the changelog vs crates.io. So you have to really understand what the tool will do.

i'm happy to redefine this behavior according to new learnings and document it thoroughly. the predictability is given in form of the dry-run feature of the github workflow.

Choosing what version should be released needs to be a human decision. The release can be kicked off by tagging the repository with a given version. E.g. "git tag -a v0.5.0-dev.1 && git push origin v0.5.0-dev.1".

in my mental model monorepos don't have versions in itself other than commit hashes. i even the timestamps that we put in the CHANGELOG headings somewhat arbitrary. the other aspect here is to be able to define the new version exactly, instead of giving the increment mode. is this preference also caused by the increment mode not being intuitive and predictable enough as of now?

Anything that needs to be versioned out of lockstep is moved out of the monorepo.

i don't know why the lockstep versioning is a requirement. on the topic of moving crates outside of it, i think there's also a risk to consider that we have no automation for releases in other repositories to the degree that we have it here. granted that with this issue you want to make a case that the state of this repo isn't ideal you may see that as a positive argument 😆

The release process can be easily tested locally without tags and commits being created that have to be tidied up. I know that some of this can be disabled currently but we don't have docs showing how so you have to figure it out each time. If we need flags then we need a documented check process.

this would mean to either (a) disregard the state of crates.io in the release process, (b) mock its API, or (c) run a standalone crates registry for CI. i don't think (a) is feasible in practice as it is fundamental part of the publish process. my preference here is (c) as it gets use closest to the production runs.

i took some notes on (c) a long time ago in a hackmd:

Test publishing with a test crate registry

• https://doc.rust-lang.org/cargo/reference/registries.html

Candidates:

• https://github.com/Hirevo/alexandrie
• https://github.com/moriturus/ktra
• https://www.meuse.mcorbin.fr/installation/launch-it/

---

despite my efforts to give thorough answers here i think there's still room for discussion. as i might still be missing context of what happened recently in my absence.

[github-actions]

This item has been open for 30 days with no activity.