Releases And Upgrading

Ferrocat follows semantic versioning from 1.0 onward: breaking API changes ship in a new major version, while minor and patch releases stay backward compatible. Start every upgrade from the changelog and keep the workspace crate versions aligned.

Where release notes live

• GitHub Releases gives the repository-level release view.
• ferrocat CHANGELOG is the best starting point for application users of the umbrella crate.
• Direct sub-crate users should also read the matching ferrocat-po or ferrocat-icu changelog for low-level parser, catalog, or ICU changes.

Release Please generates these changelogs from Conventional Commits. Breaking changes should be marked with feat!: or a BREAKING CHANGE note so they are visible in release notes and changelog sections.

MSRV bumps follow the same release-note rule. Ferrocat aligns its declared MSRV with OXC when practical while avoiding churn from tracking only the newest stable toolchain. Raising the MSRV is treated as a minor-version change and called out in the changelog; patch releases should not raise the MSRV.

Lockstep versions

The public library crates are released in lockstep: every release advances all of them to the same version. In normal application code, prefer depending on the umbrella crate:

[dependencies]
ferrocat = "1"

If you depend on lower-level crates directly, keep every Ferrocat crate on the same version line so you get the combination that was released and tested together:

[dependencies]
ferrocat-po = "1"
ferrocat-icu = "1"

Within the 1.x line, minor and patch releases stay backward compatible, so Cargo resolves a shared "1" requirement to a single, latest-compatible version. Avoid pinning the umbrella crate and a direct sub-crate to different exact versions, for example ferrocat = "=1.2.0" with ferrocat-po = "=1.0.0": that can pull two copies of the Ferrocat types into the build and fail with confusing type-mismatch errors.

Upgrade routine

1. Read the ferrocat changelog for the target version.
2. If you use direct sub-crates, read their matching changelogs too.
3. Update all Ferrocat crate requirements to the same version line.
4. Run cargo update -p ferrocat -p ferrocat-po -p ferrocat-icu when those packages are present in your lockfile.
5. Run your normal test suite plus the Ferrocat APIs you call in release or CI paths.

When a future release needs a durable migration note — for example a major version with breaking changes — this page should link that note from the upgrade routine instead of leaving it buried in a PR.