doc: update version number notes, move to contrib guide

[ci skip]

CONTRIBUTING.md

@@ -1196,6 +1196,81 @@ Finally, for quick, fine-grained performance measurements when troubleshooting o
 
 
 
+## Version numbers
+
+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 policy:
+
+- We (should) follow <http://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.
+
+hledger version numbers appear in:
+
+- the project's .version file. This is the source of truth.
+  `make setversion` propagates this version number to:
+
+- each package's package.yaml file. Here the package version, a CPP
+  VERSION macro, and bounds on other hledger packages (like >=
+  hledger-lib-VERSION && < hledger-lib-NEXTMAJORVERSION) are
+  declared. `make gencabal` or `stack build [--dry-run]`
+  propagates these to packages' .cabal files.
+
+- hledger/Hledger/Cli/Version.hs assigns VERSION to a global
+  constant accessible by other hledger code.
+
+- the doc/lib.m4 file, where it is assigned to the _version_ m4 macro.
+  Shake propagates this to all documentation generated with m4
+  (*.m4.md files).
+
+- site/js/site.js, which defines hyperlinks corresponding to all
+- released versions.
+
+- git tags for package releases, as mentioned above
+
+- the --version output (and sometimes --help output) of all hledger*
+  executables
+
+- hackage tarball filenames
+
+- hackage uris
+
+
+
 ## Sample journals
 
 Synthetic data files like `examples/100x100x10.journal` are useful for benchmarks and testing.

Makefile

@@ -692,67 +692,13 @@ haddock: \
 
 ###############################################################################
 $(call def-help-subheading,RELEASING:)
-#$(call def-help-subheading,see also developer guide -> how to -> do a release)
 
-# TODO update this:
+# old/desired release process:
-
+#  a normal release: echo 0.7   >.version; make release
-# # Version numbering. See also .version and Version.hs.
+#  a bugfix release: echo 0.7.1 >.version; make release
-# #
+#release: releasetest bumpversion tagrelease $(call def-help,release, prepare and test a release and tag the repo )
-# # hledger's version number appears in:
+#publish: hackageupload pushtags $(call def-help,upload, publish latest hackage packages and push tags to github )
-# #  hledger --version
+#releaseandpublish: release upload $(call def-help,releaseandpublish, release and upload and publish updated docs )
-# #  hledger's cabal file
-# #  darcs tags
-# #  hackage tarball filenames
-# #  hackage pages
-# #
-# # 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 darcs 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 it should be easy to darcs get the .0 release even after bugfix releases
-# # 9 avoid unnecessary compiling and linking
-# # 10 minimise rcs noise and syncing issues (commits, unrecorded changes)
-# #
-# # Current policy:
-# #
-# # - We follow http://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.
-# #
-# # - The elided release version is ma.jor when minor is 0. We use it for
-# #   hackage releases when possible, trusting it doesn't cause trouble..
-# #
-# # - 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.
-# #
-# # - The release tag in the repo is the full release version.
-# #
-# # - hledger --version shows the release version or build version as
-# #   appropriate.
-# #
-# # - The .version file must be updated manually before a release.
-# #
-# # - "make" updates the version in most other places, and defines PATCHES.
-# #   Note "cabal build" should also do this but doesn't yet.
-# #
-# # - "make release" additionally records the main version number-affected
-# #   files, and tags the repo with the release tag.
-
-# TODO revive these:
-
-# old examples: 
-# a normal release: echo 0.7   >.version; make release
-# a bugfix release: echo 0.7.1 >.version; make release
-#release: releasetest bumpversion tagrelease $(call def-help,release, prepare a release and tag the repo )
-
-#publish: hackageupload pushdocs $(call def-help,upload, publish latest hackage packages and docs )
-
-#releaseandpublish: release upload $(call def-help,releaseandupload, prepare a release and publish )
 
 ISCLEAN=git diff-index --quiet HEAD --
 
@@ -771,6 +717,16 @@ setdate: $(call def-help,setdate, set date in manuals to current month and year
 updatedate: setdate $(call def-help,updatedate, set date in manuals to current month and year and commit )
 	git commit -m "bump manual date to $(MONTHYEAR)" doc/lib.m4
 
+# Updating version numbers. See CONTRIBUTING.md Version numbers
+
+# updateversion: setdate setversion $(call def-help,updateversion, update manual date and update version strings & (lower) bounds from $(VERSIONFILE) and commit )
+# 	@read -p "please review changes then press enter to commit $(VERSIONFILE) $(VERSIONSENSITIVEFILES)"
+# 	git commit -m "bump version strings & bounds to $(VERSION)" $(VERSIONFILE) $(VERSIONSENSITIVEFILES)
+
+# XXX start with early targets isclean-$(VERSIONSENSITIVEFILES) (fails due to glob) and isdirty-$(VERSIONFILE) ?
+setversion: $(VERSIONSENSITIVEFILES) #$(call def-help,setversion, update version strings & bounds from $(VERSIONFILE) (might need -B) )
+	@echo "if this is a new major version, please manually update upper bounds in */package.yaml before generating cabal files"
+
 # update a package yaml file's version, -DVERSION, and hledger lower bounds (upper bounds must be changed manually)
 %/package.yaml: $(VERSIONFILE)
 	perl -pe "s/(^version *: *).*/\$${1}'$(VERSION)'/" -i $@                                                       # version: 'A'
@@ -784,28 +740,10 @@ doc/lib.m4: $(VERSIONFILE)
 	perl -pe "s/^(m4_define\({{_version_}}, *{{)((\d+\.)*\d+)(}}\)m4_dnl *)$$/\$${1}$(VERSION)\$${4}/" -i $@
 	@echo "please manually check/update _docversionlinks_ in doc/lib.m4"
 
-# XXX obsolete ?
-# update version string in manual
-#site/manual-start.md: $(VERSIONFILE)
-#	perl -p -e "s/(this version documents hledger and hledger-web) +[0-9.]+/\1 $(VERSION)/" -i $@
-
-# XXX start with early targets isclean-$(VERSIONSENSITIVEFILES) (fails due to glob) and isdirty-$(VERSIONFILE) ?
-setversion: $(VERSIONSENSITIVEFILES) #$(call def-help,setversion, update version strings & bounds from $(VERSIONFILE) (might need -B) )
-	@echo "if this is a new major version, please manually update upper bounds in */package.yaml before generating cabal files"
-
-# TODO: combine updateversion/updatecabal
-# minor version bump: make setdate setversion gencabal
-# major version bump: make setdate setversion, fix upper bounds in package.yamls, make gencabal
-
-# updateversion: setdate setversion $(call def-help,updateversion, update manual date and update version strings & (lower) bounds from $(VERSIONFILE) and commit )
-# 	@read -p "please review changes then press enter to commit $(VERSIONFILE) $(VERSIONSENSITIVEFILES)"
-# 	git commit -m "bump version strings & bounds to $(VERSION)" $(VERSIONFILE) $(VERSIONSENSITIVEFILES)
-
 # (re)generate a cabal file from its package.yaml definition 
 # XXX to avoid warnings, this hpack should be the same version as stack's built-in hpack
 #%.cabal: $$(dir $$@)package.yaml
 #	hpack --silent $(dir $*) 
-#
 gencabal: $(call def-help,gencabal, regenerate cabal files from package.yaml files with stack )
 	$(STACK) build --dry-run --silent
 # --stack-yaml stack-ghc8.2.yaml