hledger/doc/VERSIONNUMBERS.md

83 lines
3.1 KiB
Markdown
Raw Normal View History

# Version numbers
Some places version numbers appear:
- --version (and sometimes --help) output of all hledger* executables
- web manuals on hledger.org
- download page
- changelogs
- release notes
- release announcements
- hackage/stackage uris
- cabal tarball filenames
- platform-specific packages
Some old version numbering goals:
1. automation, robustness, simplicity, platform independence
2. cabal versions must be all-numeric
3. release versions can be concise (without extra .0's)
4. releases should have a corresponding VCS tag
5. development builds should have a precise version appearing in --version
6. development builds should generate cabal packages with non-confusing versions
7. there should be a way to mark builds/releases as alpha or beta
8. avoid unnecessary compiling and linking
9. minimise VCS noise and syncing issues (commits, unrecorded changes)
Current version numbering policy:
- We (should) follow <https://haskell.org/haskellwiki/Package_versioning_policy>
- The "full release version" is ma.jor.minor, where minor is 0 for a
normal release or 1..n for bugfix releases. Each component is a
natural number (can be >= 10). Eg: 1.13 major release, 1.13.1
bugfix release.
- The "release version", which we prefer to use when possible, is
just ma.jor when minor is 0. Ie elide the dot zero.
- The build version is ma.jor.minor+patches, where patches is the number
of patches applied in the current repo since the last release tag.
- `hledger --version` shows the release version or build version as
appropriate.
- Release tags in the VCS are like PKG-VERSION. Eg hledger-1.13,
- hledger-ui-1.13.1.
Current process:
- In each hledger package directory there's a `.version` file
containing its desired version number.
- After changing a `.version` file: run `./Shake setversion` to
propagate the versions to all other places in the packages where
they should appear. This is not perfect (see Shake.hs) so review and
manually adjust the proposed changes before committing. Those
places include (you can also run these rules individually):
- `PKG/package.yaml` contains the cabal package version declaration,
bounds on other hledger packages, and a CPP VERSION macro used in
`hledger/Hledger/Cli/Version.hs`. Changes in package.yaml will be
propagated to `PKG/PKG.cabal` on the next stack build or --dry-run build
or with `just cabalfiles`.
- `PKG/.version.m4` contains the _version_ macro used in documentation source files (*.m4.md). It is updated by `./Shake setversion`.
- `PKG/.date.m4` contains the _monthyear_ macro used in man pages. It is updated by `./Shake manuals`.
- At release time:
- `./Shake PKG/CHANGES.md-finalise` converts the topmost heading, if
it is an interim heading (just a commit hash), to a permanent
heading containing the version and today's date.
- for each package being released, a PKG-VERSION git tag is created.
- At major release time:
- A new snapshot of the reference docs is added to the website, by
`./Shake site/doc/VERSION/.snapshot`, and added to the links in
`site/js/site.js`.