From 3fdae997dc5731f434d3d159537d4f4306170b5b Mon Sep 17 00:00:00 2001 From: Joachim Nilsson Date: Tue, 15 Oct 2019 05:49:54 +0200 Subject: Replace release checklist with new HACKING.md Outline: - maintenance duties - release checklist - library versioning Signed-off-by: Joachim Nilsson --- bin/Changelog | 1 - doc/HACKING.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++ doc/RELEASE-CHECKLIST.txt | 33 -------------- 3 files changed, 113 insertions(+), 34 deletions(-) delete mode 100755 bin/Changelog create mode 100644 doc/HACKING.md delete mode 100644 doc/RELEASE-CHECKLIST.txt 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 -- cgit v1.2.1