主题： release-management
-
Tags and releases: lightweight versus annotated tags and how they travel
A lightweight tag is only a name for a commit; an annotated tag is an object with tagger, date, message and optional signature, which is why git describe ignores lightweight tags by default and why releases should use annotated or signed tags; tags are not pushed with branches unless --follow-tags or --tags is used, and a published tag should never be moved.
-
Cherry-picking: when it fits and what it costs the history
git cherry-pick replays the change of a commit as a new commit with a different ID; it is the right tool for backporting a fix to a maintenance branch or salvaging one commit from an abandoned branch, but each pick creates a duplicate that merges cannot recognise, so record the origin with -x and merge instead of picking when the whole branch is wanted.
-
Release cadence for a small project: time-based trains versus release-when-ready
A version number says what a release promises; a cadence policy says when releases happen. Rust ships a stable release every six weeks from a nightly, beta, stable train, Python moved to an annual feature release with PEP 602, and Django issues feature releases on a time-based schedule with patch releases as needed. A small project can copy the shape: feature releases on a calendar or when something notable accumulates, patch releases whenever a fix lands.
-
Deprecating a function in a library: warn, document the replacement, remove on schedule
A library deprecation has four parts: a replacement that exists first, a runtime warning plus a documentation note naming the version and the replacement, a changelog entry, and a removal release fixed in advance by policy. PEP 387 requires a deprecation period of at least two years under Python's annual cadence and describes a documentation-only soft deprecation; Django removes shims no earlier than two feature releases after the warning.
-
Conventional Commits: machine-readable commit types
The Conventional Commits specification adds a typed prefix (feat, fix, and others) and breaking-change markers to commit messages so that changelogs and version bumps can be derived automatically.
-
Semantic Versioning: what a version number promises
Semantic Versioning 2.0.0 encodes compatibility promises in MAJOR.MINOR.PATCH and defines pre-release and build-metadata suffixes; it works only when the public API is declared.
-
API versioning: when and how to break compatibility
Most changes can be additive; a new major version is a last resort that doubles the surface to support. Version in the path or media type, document the compatibility rules, and deprecate before removing.
-
Supporting several release lines: which fixes go where
A support policy is a table of release lines with a status each (feature, bugfix, security-only, end of life) and a rule for which fix classes are backported to which lines. Python maintains a series with bugfix releases for two years and security-only releases for three more; Django backports critical fixes to the last feature release and security and data-loss fixes to the last two plus long-term-support lines; Rust supports only the most recent stable. A small project should publish the table and default to the narrowest promise it can keep.
-
Keeping a changelog for humans
A changelog is a curated, chronologically ordered list of notable changes per version; Keep a Changelog defines a small structure (Added, Changed, Deprecated, Removed, Fixed, Security) and an Unreleased section.
机器可读： JSON