Release engineering notes

Release engineering environment

Release engineering operations are currently performed on a Ubuntu 14.04 host. Updates to the Ubuntu version may cause churn in the generated files which are checked into the repository due to newer versions of programs in the toolchain.

The release engineering host must have the following packages installed:

• autoconf
• build-essential
• dejagnu
• doxygen
• git
• keyutils
• ldap-utils
• libkeyutils-dev
• libldap2-dev
• libssl-dev
• libtool
• python-sphinx
• python-cheetah
• rcs
• slapd
• tcl-dev
• texlive
• texlive-latex-extra

Pulling up changes to release branches

• For each supported release (usually the most recent and one previous release), prepare a git working copy with the krb5-x.y branch checked out from the authoritative repository. From the krbdev-services repository, copy githooks/hookutils.py and githooks-client/prepare-commit-msg into .git/hooks for both working copies.

• Check that each working copy is clean, has no unexpected extra commits, and is up to date with the authoritative repository. Checking the output of "git status" and running "git pull" should accomplish this.

• At https://krbdev.mit.edu/rt/ , start a new search, add the criteria "queue is krb5", then the criteria "tags is pullup", then search. It can be useful to create a browser tab for each search result.

• If there has been a calendar year change since the last patch release, pull up the commit(s) which bump the project-wide copyright years as well.

• For each release branch:
  • For each ticket marked for pullup to that branch:
    • For each commit listed in the ticket, run "KRB5_VERSION_FIXED=x.y.z git cherry-pick -x COMMIT", and address any merge conflicts. x.y.z should be the next patch release that will be created on the release branch.
    • Examine the commits any consider any possible interactions with changes made since the release branch.
    • Run "make" and "make check".
    • If the change isn't covered by automated tests, consider testing it by hand.
• Consider pushing the updated release branches to a personal github fork integrated with Travis, and waiting for Travis to finish building and testing it.
• If the pulled up changes are substantial, consider running a build and check of each release branch on krbdev-sparc-build.
• Push the updated release branches to the authoritative repository.
• Remove the "pullup" tag from each ticket. This can be done in a bulk update from the search result page using the button at the lower right, or it can be done on each ticket individually from the jumbo page.

Preparing releases

Pre-mkrel

• check copyright years in project-wide stuff
• update config.guess and config.sub from git://git.savannah.gnu.org/config.git (only for minor releases, not patch releases)
• make sure you're in a build tree that's not the source tree and configured using --enable-maintainer-mode
• make depend and commit if changed, with the commit message "make depend"
• regenerate manpages: (cd man && make man) and commit if changed, with the commit message "Update man pages"
• regenerate localization template (cd po && make update-po) and commit if changed, with the commit message "make update-po"
• manually edit patchlevel.h to reflect the new release
  • for a patch release, increment KRB5_PATCHLEVEL, change the next line to "/* #undef KRB5_RELTAIL */", and change KRB5_RELTAG to "krb5-x.y.z-final"
• manually update README
  • release dates (in major changes heading, ISO 8601 date format with hyphens)
  • changes
    • note whether bugfix release, maintenance vs current release
    • bullet list of major changes
    • minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these! (https://krbdev.mit.edu/rt/NoAuth/Fixed?rel=x.y.z)
  • contributors (RT is a good source for these; click through the ticket links from the above URL and look for reporter and patch author names)
  • double-check dates and release numbers in new section headings
• re-run (cd man && make man) and (cd po && make update-po) with updated patchlevel.h
  • If there is no update to Project-Id-Version in mit-krb5.pot, touch configure.in and re-run make, then run (cd po && make update-po) again.
• commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"
• git tag krb5-x.y.z-final

Running mkrel

• path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z
• manually inspect output for versioning and correctness
  • HTML docs
  • PDF docs
  • patchlevel.h as modified by mkrel
• push release branch commits to authoritative repository

Post-mkrel

• PGP sign (gpg -ab krb5-x.y.z.tar.gz, generates krb5-x.y.z.tar.gz.asc)
• copy tar file and signature into /mit/kerberos/dist/x.y
• create /mit/kerberos/krb5-x.y/krb5-x.y.z and /mit/kerberos/krb5-x.y/krb5-x.y.z/doc
• copy signature to /mit/kerberos/krb5-x.y/krb5-x.y.z.sig
• copy README from release source code to /mit/kerberos/krb5-x.y/README-x.y.z.txt
• generate branded HTML docs
  • HTML_LOGO=/mit/kerberos/mitkc-logo-sm.png make html
  • we don't ship the branded (with logo) docs because the logo is an MIT trademark
  • copy the resulting documentation tree to /mit/kerberos/krb5-x.y/krb5-x.y.z/doc/html
  • repeat for HTML_LOGO=... make pdf and .../doc/pdf
• update RT configuration
  • on RT server, create files in /var/rt2/local/WebRT/html/NoAuth/krb5-x.y for new release
  • check that http://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work
  • in the web interface, to go Configuration -> Keywords -> k5 -> version and add a new one for the next patch release
• edit web pages
  • create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example
  • update /mit/kerberos/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old news items to oldnews.html
  • update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases)
  • update /mit/kerberos/dist/historic.html with entries for any previously current releases which are no longer current
  • update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks
  • update /mit/kerberos/latest symlink if this is a major or minor release
• send announcement to kerberos-announce
• make followup versioning commit to release branch
  • edit src/patchlevel.h, setting KRB5_RELTAIL to "postrelease" and KRB5_RELTAG to "krb5-x.y"
  • use the commit message "Update for krb5-x.y.z-postrelease"