ADR 003-Zaino Branching, Versioning, Documentation, Public Interfaces, and Release Strategy#3
ADR 003-Zaino Branching, Versioning, Documentation, Public Interfaces, and Release Strategy#3
Conversation
idky137
changed the title
|
First step required for: zingolabs/zaino#823 |
|
Closes #2 |
AloeareV
left a comment
AloeareV
left a comment
There was a problem hiding this comment.
Very nice! I want to argue in favor of per-crate versions, rather than a workspace-wide shared library version.
| Zaino follows **Semantic Versioning (SemVer)**: `MAJOR.MINOR.PATCH`. ([semver.org](https://semver.org/spec/v2.0.0.html)) | ||
|
|
||
| **Scope choice** | ||
| - Zaino versions are treated as **workspace-wide** (a coordinated release), meaning all publishable crates in this repository share the same version bump in a given release. |
There was a problem hiding this comment.
I think crate-specific versions are superior to workspace-wide ones. With workspace-wide scoping, making a breaking chain in any zaino crate forces a major version bump in all zaino crates. I think semantic versioning is much more meaningful in the case where only changes to an individual crate effect that crate's version.
There was a problem hiding this comment.
I get what you mean am I'm happy for us to use crate level versioning rather than workspace level.
My reasoning was that it is more simple to maintain but agree crate level versioning is more meaningful.
The thing we will need to pay extra attention to if we do use crate level versions is structs / interfaces from upstream crates being updated and changing the public interface of the consuming downstream crates, which would necessitate a version bump of both crates even if only the lower level crate was updated.
An example of this could be a struct updated in zaino-common changing the API of an interface in another crate.
There was a problem hiding this comment.
If a breaking change happens in (for example) zaino-state, it feels like an anti-pattern to also require an update to zaino-common if no changes were made in zaino-common. If feels wrong to me...but I'm not sure it actually matters, I haven't yet thought of a way this actually breaks anything.
If a struct updates in zaino-common, this requires a breaking version update in all crates which expose a type from zaino-common in their public interfaces. I guess the simplest way to do this is to have workspace-wide version...on the other hand, I do think it's valuable to be able to see a major/minor version number update in zaino-state, and know that that actually represents a API-level change to zaino-state.
There was a problem hiding this comment.
The more you put forward this point the more I agree with it.
I think I'm now in agreement with you that we should use crate level versions.
We just need to make sure we write the release checklist to include the extra step of checking crate versions are correct.
There was a problem hiding this comment.
Maybe we could even define a dependency tree for our crates instead of structs / types?
This way instead of having to look though everything in the public surface of a crate that has changed, and propagate individual changes up through higher level crates, we could just look at which crates have been version bumped, and bump the versions of all crates that are above that crate in the dependency tree?
Edit: thinking about this more it may not be the best approach as it could be possible for zaino-state to have it's version bumped without any change to it's pub surfaces.
|
|
||
| **Scope choice** | ||
| - Zaino versions are treated as **workspace-wide** (a coordinated release), meaning all publishable crates in this repository share the same version bump in a given release. | ||
| - This avoids “version skew” across tightly-coupled crates and matches established practice in multi-crate Rust workspaces that ship as a unit. |
There was a problem hiding this comment.
What's the downside of version skew? Workspace-wide scoping is definitely common in the rust ecosystem, but I don't think it's ubiquitous enough that we'll run into problems purely due to doing things against the standard. A lot of workspaces do use individual crate versions (including librustzcash).
There was a problem hiding this comment.
The main downside i see is that if differing versions are incompatible then users have to manually check which version of each crate they should be importing to not cause import conflicts, where as if all versions are matched it is simple for users to know which versions to use.
|
One thing that's not mentioned here but could be useful to incorporate is release candidates. If we do use release candidates, how should we use them? I assume they would be git tags but not pushed to crates.io. |
AHH good catch! What I had in my head originally is we could tag release candidates from dev (vx.y.z-rc) and then once this is accepted update stable with dev and put the actual release out from stable. I'm not sure of this is too complicated though? |
2 participants
Poposes new adr - 'ADR 003-Zaino Branching, Versioning, Documentation, Public Interfaces, and Release Strategy.md'