docs/HACKING.md: Add release checklist and maintenance doc

Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

docs/HACKING.md

@@ -0,0 +1,106 @@
+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
+* Bump library ABI version just before release!
+
+
+Release Checklist
+-----------------
+
+* Update ChangeLog, follow http://keepachangelog.com/ loosely
+  - Inform users in a plain language of changes and bug fixes
+  - Do *not* copy-paste GIT commit logs!
+  - Order entries according to importance, most relevant first
+* Run unit tests: `make check`
+* Make at least one `-rcN` release and test it in an actual real project
+* **REMEMBER:** bump ABI version according to below rules
+* Tag
+* Push last commit(s) *and* tags to GitHub
+* Make release
+
+        make distclean
+        ./autogen.sh
+        ./configure
+        make release
+
+* Create new release in GitHub releases page
+* Copy and paste ChangeLog entry, check any stale links!
+* Upload release tarball and MD5 files
+
+
+Library Versioning
+------------------
+
+Editline relies on GNU Libtool for building the library.  For a user of
+the library it is important to maintain a clear ABI versioning scheme.
+This is not the same as the Editline version, but rather the library
+"compatibility level".
+
+The Editline ABI version is specified in `src/Makefile.am` and looks
+like this:
+
+    libeditline_la_LDFLAGS = -version-info 0:0:0
+                                            \ \ `-- age
+                                             \ `--- revision
+                                              `---- current
+
+It must be updated according to the [GNU Libtool recommendations][1]:
+
+1. Start with version information of `0:0:0` for each libtool library.
+2. Update the version information only immediately before a public
+   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` 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 `libeditline.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
+ `libeditline.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
+the library version just prior to a release, point 2.
+
+However, if releases are few and far between, distributors may start to
+use snapshots.  When a distributor uses a snapshot, the distributor has
+to handle the library version manually.  Things can get ugly when the
+distributor has released an intermediate version with a bumped library
+version, and when the official release is bumped to that version, the
+distributor will then have to bump the library version for the official
+release, and it can be confusing if someone reports bugs on versions
+that you didn't even know existed.
+
+The problem with bumping the version with every change is that if your
+interface is not finished, the version number might run away, and it
+looks pretty bad if a library is at version 262.  It kind of tells the
+user that the library interface is volatile, which is not good for
+business.
+
+[1]: https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html