# 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`.

