Replace release checklist with new HACKING.md

Outline:
 - maintenance duties
 - release checklist
 - library versioning

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

3 files changed, 113 insertions, 34 deletions

diff --git a/bin/Changelog b/bin/Changelog
deleted file mode 100755
index 32b7cff..0000000
--- a/bin/Changelog
+++ /dev/null
@@ -1 +0,0 @@
-git --no-pager log --no-merges --pretty=format:' %x20%x20 - %s (%an)' `git tag | grep -v -- -rc | tail -n 1`..HEAD .
diff --git a/doc/HACKING.md b/doc/HACKING.md
new file mode 100644
index 0000000..d340f2f
--- /dev/null
+++ b/doc/HACKING.md
@@ -0,0 +1,113 @@
+Maintenance and Release Checklist
+=================================
+
+Maintenance
+-----------
+
+* Leverage GitHub issues for milestone planning
+* Reference issues from GitHub pull requests to alert issue subscribers
+* Use version in `configure.ac` for -betaN/-rcN and GA releases
+* Bump ABI version in `src/Makefile.am` just before release! (see below)
+
+
+Release Checklist
+-----------------
+
+* Bump version to -betaN/-rcN or GA version to be released
+* 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 using `vMAJOR.MINOR[.PATCH]` syntax, `.PATCH` optional
+
+        git tag v1.2
+
+* Push last commit(s) *and* tags to GitHub
+
+        git push
+		git push --tags
+
+* 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 in *Preview*!
+* Upload release zip/tarball and MD5 files from `make release` stage
+
+
+Library Versioning
+------------------
+
+Libnet 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 Libnet version, but rather the library
+"compatibility level".
+
+The Libnet ABI version is specified in `src/Makefile.am` and looks
+like this:
+
+    libnet_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 `libnet.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
+ `libnet.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
diff --git a/doc/RELEASE-CHECKLIST.txt b/doc/RELEASE-CHECKLIST.txt
deleted file mode 100644
index 75589fa..0000000
--- a/doc/RELEASE-CHECKLIST.txt
+++ /dev/null
@@ -1,33 +0,0 @@
-Release Checklist
-=================
-
-Pre-release:
-
-- doc/CHANGELOG
-
-Use ../ChangeLog to update changelog.
-
-- README.txt, libnet/README
-
-Sync these.
-
-- configure.ac
-
-Update version.
-
-- src/Makefile.am
-
-Update LDFLAGS' version-info.
-
-- tag it, with -rc#
-
-> git tag -a libnet-x.y.z -m libnet-x.y.z
-> git push --tags
-
-- Build it, ../Build
-
-- Push it, ../Push
-
-- Announce release-candidate on libnet-dev-announce and to people in doc/CONTRIB
-
-- Announce release on libnet-dev-announce