RELEASING.md

   1 HarfBuzz release walk-through checklist:
   2
   3 1. Open gitk and review changes since last release.
   4
   5    * `git diff $(git describe | sed 's/-.*//').. src/*.h` prints all public API
   6      changes.
   7
   8      Document them in NEWS.  All API and API semantic changes should be clearly
   9      marked as API additions, API changes, or API deletions.  Document
  10      deprecations.  Ensure all new API / deprecations are in listed correctly in
  11      docs/harfbuzz-sections.txt.  If release added new API, add entry for new
  12      API index at the end of docs/harfbuzz-docs.xml.
  13
  14      If there's a backward-incompatible API change (including deletions for API
  15      used anywhere), that's a release blocker.  Do NOT release.
  16
  17 2. Based on severity of changes, decide whether it's a minor or micro release
  18    number bump,
  19
  20 3. Search for REPLACEME on the repository and replace it with the chosen version
  21    for the release.
  22
  23 4. Make sure you have correct date and new version at the top of NEWS file,
  24
  25 5. Bump version in configure.ac line 3,
  26
  27 6. Do "make distcheck", if it passes, you get a tarball.
  28    Otherwise, fix things and commit them separately before making release,
  29    Note: Check src/hb-version.h and make sure the new version number is
  30    there.  Sometimes, it does not get updated.  If that's the case,
  31    "touch configure.ac" and rebuild.  Also check that there is no hb-version.h
  32    in your build/src file. Typically it will fail the distcheck if there is.
  33    That's what happened to 2.0.0 going out with 1.8.0 hb-version.h...  So, that's
  34    a clue.
  35
  36 7. Now that you have release files, commit NEWS, configure.ac, and src/hb-version.h,
  37    as well as any REPLACEME changes you made.  The commit message is simply the
  38    release number.  Eg. "1.4.7"
  39
  40 8. "make dist" again to get a tarball with your new commit in the ChangeLog.  Then
  41    "make release-files".  Enter your GPG password.  This creates a sha256 hash
  42    and signs it.  Check the size of the three resulting files.
  43
  44 9. Tag the release and sign it: Eg. "git tag -s 1.4.7 -m 1.4.7".  Enter your
  45    GPG password again.
  46
  47 10. Build win32 bundle.
  48
  49    a. Build Win32 binaries.  See [README.mingw.md](README.mingw.md).
  50
  51    b. Run "make dist-win" to build Win32 bundle.
  52
  53 11. Copy all artefacts to users.freedesktop.org and move them into
  54     `/srv/www.freedesktop.org/www/software/harfbuzz/release` There should be four
  55     files.  Eg.:
  56  ```
  57 -rw-r--r--  1 behdad eng 1592693 Jul 18 11:25 harfbuzz-1.4.7.tar.xz
  58 -rw-r--r--  1 behdad eng      89 Jul 18 11:34 harfbuzz-1.4.7.tar.xz.sha256
  59 -rw-r--r--  1 behdad eng     339 Jul 18 11:34 harfbuzz-1.4.7.tar.xz.sha256.asc
  60 -rw-r--r--  1 behdad eng 2895619 Jul 18 11:34 harfbuzz-1.4.7-win32.zip
  61 ```
  62
  63 12. While doing that, quickly double-check the size of the .tar.xz and .zip
  64     files against their previous releases to make sure nothing bad happened.
  65     They should be in the ballpark, perhaps slightly larger.  Sometimes they
  66     do shrink, that's not by itself a stopper.
  67
  68 13. Push the commit and tag out: "git push --follow-tags".  Make sure it's
  69     pushed both to freedesktop repo and github.
  70
  71 14. Go to GitHub release page [here](https://github.com/harfbuzz/harfbuzz/releases),
  72     edit the tag, upload artefacts and NEWS entry and save.