From fd65af31db69b55afebca1a2c9dde02791aae9e8 Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Sun, 2 Jul 2017 19:13:26 +0200 Subject: [PATCH] Update HACKING document, mostly wrt library versioning Signed-off-by: Joachim Nilsson --- HACKING.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/HACKING.md b/HACKING.md index 7544ce6..fbe4adc 100644 --- a/HACKING.md +++ b/HACKING.md @@ -4,9 +4,10 @@ Maintenance and Release Checklist Maintenance ----------- +* Encourage contributors to write tests, in particular for new features +* Run tests regularly, use Travis-CI to do this automatically * Leverage GitHub issues for milestone planning * Reference issues from GitHub pull requests to alert issue subscribers -* Encourage contributors to write unit tests * Bump library ABI version just before release! @@ -17,6 +18,7 @@ Release Checklist - Inform users in a plain language of changes and bug fixes - Do *not* copy-paste GIT commit logs! - Order entrys according to importance, most relevant first +* Run unit tests: `make check` * Do we need to bump the ABI version? (Probably, see below) * Tag * Push last commit(s) *and* tags to GitHub @@ -25,7 +27,7 @@ Release Checklist make distclean ./autogen.sh ./configure - make release + make release * Create new release in GitHub releases page * Copy and paste ChangeLog entry, check any stale links! @@ -54,14 +56,31 @@ It must be updated according to the [GNU Libtool recommendations][1]: release of your software. More frequent updates are unnecessary, and only guarantee that the current interface number gets larger faster. 3. If the library *source code has changed at all* since the last update, - then increment revision (`c:r:a` --> `c:r+1:a`) -4. If any *interfaces have been added, removed, or changed* since last - update, increment current, and zero revision (`c:r:a` --> `c+1:0:0`) + then increment revision (`c:r:a` becomes `c:r+1:a`). +4. If any *interfaces have been added, removed, or changed* since the + last update, increment current, and set revision to 0. 5. If any *interfaces have been added* since the last public release, then increment age. 6. If any *interfaces have been removed or changed* since the last public release, then set age to 0. +The libtool ABI versioning logic is very confusing but works if you just +disable your brain and follow the rules, one by one. + +**Example #1:** a new function has been added, none of the existing ones +have changed. The initial version is 1:0:0, we follow the rules above to +the letter: increase revision, increase current and set revision to zero, +and finally increase age. This, rather confusingly, gives us 2:0:1 which +libtool then translates to `libconfuse.so.1.1.0`. + +**Example #2:** some existing functions are changed, they now return an +`int` instead of `void`. The initial version is 0:0:0, and we follow the +rules again: increment revision, increment current and set revision to +zero, set age to zero. This gives us 1:0:0, which is then translated to + `libconfuse.so.1.0.0`. + +### Note + Usually, non-developers have no interest in running development versions (releases are frequent enough), and developers are expected to know how to juggle versions. In such an ideal world, it is good enough to bump