Skip to content

Latest commit

 

History

History
154 lines (114 loc) · 6.43 KB

faq.md

File metadata and controls

154 lines (114 loc) · 6.43 KB
Raw

FAQ

How do I update my README or other files

Cargo-release 0.8 allows you to search and replace version string in any project or source file.

For example, to update the version in predicates README.md:

[dependencies]
predicates = "1.0.2"

You use the following release.toml:

pre-release-replacements = [
  {file="README.md", search="predicates = .*", replace="{{crate_name}} = \"{{version}}\""},
  {file="src/lib.rs", search="predicates = .*", replace="{{crate_name}} = \"{{version}}\""},
]

Note: we only substitute variables on replace and not search so you'll need to change predicates to match your crate name.

See pre-release-replacements for more.

Maintaining Changelog

At the moment, cargo release is unopinionated in its support for CHANGELOGs due to the complexities and the different approaches people might want to take (see Issue #231).

As a CHANGELOG is better than no changelog, a low-effort approach would be to use git-cliff as a pre-release hook.

pre-release-hook = ["git", "cliff", "-o", "CHANGELOG.md", "--tag", "{{version}}" ]

For hand-written CHANGELOGs, you can automate parts of the process with pre-release-replacements. Say you follow Keep a Changelog and keep unreleased changes in an Unreleased section:

<!-- next-header -->

## [Unreleased] - ReleaseDate

### Added
- feature 3

### Changed
- bug 1

## [1.0.0] - 2017-06-20
### Added
- feature 1
- feature 2

<!-- next-url -->
[Unreleased]: https://github.com/assert-rs/predicates-rs/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/assert-rs/predicates-rs/compare/v0.9.0...v1.0.0

In release.toml, configure cargo release to do replacements while bumping version:

pre-release-replacements = [
  {file="CHANGELOG.md", search="Unreleased", replace="{{version}}"},
  {file="CHANGELOG.md", search="\\.\\.\\.HEAD", replace="...{{tag_name}}", exactly=1},
  {file="CHANGELOG.md", search="ReleaseDate", replace="{{date}}"},
  {file="CHANGELOG.md", search="<!-- next-header -->", replace="<!-- next-header -->\n\n## [Unreleased] - ReleaseDate", exactly=1},
  {file="CHANGELOG.md", search="<!-- next-url -->", replace="<!-- next-url -->\n[Unreleased]: https://github.com/assert-rs/predicates-rs/compare/{{tag_name}}...HEAD", exactly=1},
]

{{version}} and {{date}} are pre-defined variables with value of current release version and date.

predicates is a real world example

How do I apply a setting only to one crate in my workspace?

Example problems:

  • Release fails because cargo-release was trying to update a non-existent CHANGELOG.md (#157)
  • Only create one tag for the entire workspace (#162)

Somethings only need to be done on for a release, like updating the CHANGELOG.md, no matter how many crates are being released. Usually these operations are tied to a specific crate. This is straightforward when you do not have a crate in your workspace root.

When you have a root crate, it shares its release.toml with the workspace, making it less obvious how to do root-crate-specific settings. If you'd like to customize settings differently for the root crate vs the other crate's, you have two choices:

  • Put the common setting in the workspace's release.toml and override it for the root crate in Cargo.toml.
  • Modify each crate's release.toml with the setting relevant for that crate.

How do I customize my tagging in a workspace?

Example problems:

  • Customizing tags while needing the root workspace to follow a specific convention (#172)

By default, your tag will look like:

  • v{{version}} if the crate is in the repo root.
  • {{crate_name}}-v{{version}} otherwise.

This is determined by tag-name with the default "{{prefix}}v{{version}}".

  • "{{prefix}}" comes from tag-prefix which has two defaults:
    • "" if the crate is in the repo root.
    • "{{crate_name}}-" otherwise.
  • "{{version}}" is the current crate's version.

Other variables are available for use. See the reference for more.

tag-name, tag-prefix come from the config file and cargo-release uses a layered config. The relevant layers are:

  1. Read from the crate's Cargo.toml
  2. Read from the crate's release.toml
  3. Read from the workspace's release.toml.

Something to keep in mind is if you have a crate in your workspace root, it shares the release.toml with the workspace. If you'd like to customize the tag differently for the root crate vs the other crate's, you have two choices:

  • Put the common setting in the workspace's release.toml and override it for the root crate in Cargo.toml.
  • Modify each crate's release.toml with the setting relevant for that crate.

How do I do a release when there is dependency cycle in my workspace?

If this is for dev-dependencies, just declare your dev-dependency with only a path, no version, and it should work out.

If you have other cycles, open an issue, we'd love to hear about your use case and see how we can help!

Why does cargo-release say a package has changes and needs to be released?

If you run with extra logging, we'll call out which file changed that triggered the release.

If that file shouldn't be included in the package, update your Cargo.toml's include and exclude fields.

How do I automate creating a Release on Github

We recommend creating a workflow that creates a Release based on tags being published

How do I support cargo binstall

See cargo nextest as an example workflow for this