Skip to content

Latest commit

 

History

History
106 lines (78 loc) · 6.69 KB

README.md

File metadata and controls

106 lines (78 loc) · 6.69 KB

cargo smart-release

Fearlessly release workspace crates and with beautiful semi-handcrafted changelogs.

asciicast

Key Features

  • zero-configuration
    • cargo smart-release needs no extra flags to do the right thing™️ smartly. If your intervention is needed it will let you know before it makes changes.
    • It won't do anything if there are no changes.
  • made for multi-crate workspaces
    • "Nothing stands by itself, and everything is interconnected" - is how it sees the world, allowing it to efficiently handling complex workspace graphs.
    • works just as well for single-crate workspaces
  • changelogs-deluxe
    • It maintains beautiful changelogs for you while allowing you to edit them for the final polish.
    • See your release notes via in-repository tag objects and in GitHub Releases
    • plays well with cargo release
      • cargo changelog writes changelogs non-destructively, and only that, leaving the release workflow to cargo-release.

If seeing is believing, here is a 12 minute demonstration, and the same in 30 minutes is also available.

Made for this Workflow

When developing various crates in a workspace, when committing changes and if the edit is breaking, a feature, or another change I want to see in changelogs, conventional git messages will be used. This helps building changelog scaffolding automatically later.

When ready for releasing a particular crate or set of crates of interest, run cargo smart-release [<crate-name> ...] to simulate a release. For particularly thorough but error-prone simulations (as in false positives) one could run cargo smart-release --dry-run-cargo-publish. To polish changelogs, run cargo changelog --write <crate-name> to update the scaffolding and edit it by hand until it fits.

After evaluating the release procedure and following instructions, cargo smart-release --execute will cause the fully automatic release of one or more crates.

There are various other options that shouldn't be needed in the common case, use cargo smart-release --help to see them.

Installation

Cargo

Via cargo, which can be obtained using rustup

cargo install cargo-smart-release

Features

  • safe to use as actually performing an operation requires the --execute flag
  • avoid inconsistent states by making operations as atomic as possible, leveraging gitoxide technology to the fullest
  • handle workspace dependencies and cycles gracefully, allowing one invocation to publish multiple crates
  • avoid making any releases if there are no changes
  • avoid bumping versions if the current version isn't released, allowing you to control the version by editing the cargo manifest
  • conventional commit message drive changelog scaffolding and to automatically derive the crate version to publish
  • automatically release dependent workspace IDP crates along with the desired one if they changed since their last release
  • automatically adjust manifest versions and update manifests of crates which use those whose versions were incremented
  • conservatively bump downstream workspace crates in the light of breaking changes, even though these won't be published, making downstream breakage impossible
  • use git tags to know if a crate changed at all, skipping publishes if there is no code change at all
  • it's too eager to release and there should be a way to control patch releases.
  • Handle pre-release versions, like 1.0.0-beta.1
  • Support other remote names than 'origin' - currently the latter name is assumed. Fix by getting the remote of the currently checked out branch.
  • handle version specifications correctly (tables vs values)
  • handle all version comparators correctly (see here for how it's done)
  • Automatically detect if crate changes are breaking to suggest the correct version increment

Comparison to cargo release

cargo-release is the reason this tool exists, as it got me addicted to an all automatic release workflow that knows git. This works perfectly for simple workspaces or single-crate workspaces, as of 2021-08-12, so use it: cargo install cargo-release.

Here is what cargo smart-release does differently: "It tries really hard to do what I want most of the time when publishing workspace gitoxide crates".

  • be safe to execute, so it's disarmed by default
  • specify one or more crates, and detect which crates need publishing automatically
  • handle dependency cycles in such a way that increases the chances of overall success
  • try really hard to not leave the workspace in an inconsistent state when something goes wrong
  • be a playground for gitoxide to have a reason to make it much more convenient and more feasible for application authors (aka dog-fooding)
  • create changelogs non-destructively, along with annotated tags and GitHub releases

Limitations

  • it requires tables to be used when specifying versions, i.e. crate = { version = "1" } instead of `crate = "1".
  • it gracefully fails when encountering version requirement comparators which are not ^, like =
  • it's tested only by using it on gitoxide, there are only very few regression tests with little coverage.
  • short object ids in changelogs may be ambiguous, as they are unconditionally truncated to 7 characters.
  • changelog rewriting of user content will drop links if they are not of the 'inline' form
  • it's very young and probably tries to eat underwear
  • it needs a git repository to govern the workspace

Changelogs

  • When determining if something changed in top-level crates, only the src/ directory is used, unless there is only a single crate in the workspace. This value is hard-coded.
  • For change tracking, it will only obtain manifest values once to know where a crate lives, and expects it to not be moved.
  • If list items populated by commit messages contain items themselves, round-tripping will fail. Ideally there was a way to parse an item on the same level only.

Acknowledgements

Thanks to cargo-release for showing the way and for incredible fast response times. I'd recommend everyone to participate there instead of writing your own.

Special thanks go to git-cliff which gave me the nudge needed to want to write my own.