Difference between revisions of "Release engineering notes"

Latest revision as of 13:44, 6 July 2023

Release engineering environment

Release engineering operations are currently performed on a Ubuntu 18.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
bison
build-essential
dejagnu
doxygen
flex
git
keyutils
ldap-utils
libcmocka-dev
libkeyutils-dev
libldap2-dev
liblmdb-dev
libresolv-wrapper
libsasl2-dev
libssl-dev
libtool
pkg-config
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:444/rt/ , start a new search, add the term "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. If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.
  - Examine the commits any consider any possible interactions with changes made since the release branch.
  - Run "make" and "make check". Remember that "make check" will not work for multiple working directories concurrently on the same host.
  - 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 and waiting for Github Actions 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, or it can be done on each ticket individually from the jumbo page.

Creating a new release branch

At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values. Do the same for Version_Fixed.
At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:
- Queue is krb5
- Status is resolved
- Version_Fixed is (no value)
- Tags is not unsupported
- Tags is not noresource
- Tags is not nochange
Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.
On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers. Write up a list of major changes for the new release, broken down by category. Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers. Commit with the subject "Update features list for x.y".
On the master branch, update config.guess and config.sub from git://git.savannah.gnu.org/config.git. Commit with the subject "Update config.guess, config.sub"
On the master branch, run "make regen". Commit with the subject "make regen". Push the master branch to the authoritative repository.
Create the new branch and push it to the authoritative repository.
On the new branch, update README for the new release:
- Make sure that all x.y references are for the new version (they should be already).
- Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.
- Include the list of major changes for the new release.
- Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).
- Copy the list of contributors from the previous release branch.
- Add contributors from the RT tickets for the new release branch.
- Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.
On the master branch, update README for the next prerelease:
- In README, update x.y references to x.(y+1), and update the list of contributors and any changes to transitional notes from the x.y branch.
- In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.
- Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.
Update web pages
- Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory
- Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS

Preparing releases

Pre-mkrel

check copyright years in project-wide stuff
make sure you're in a build tree that's not the source tree and configured using --enable-maintainer-mode
make regen and commit if there is more than just a pot file date change, with the commit message "make regen"
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"
- for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.
manually update README
- release dates (in major changes heading, ISO 8601 date format with hyphens)
  - we do not have release dates for alpha or beta releases; add one when making the first final x.y release
- 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/krb5-x.y/fixed-x.y.z.html)
- 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 make regen with updated patchlevel.h
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 (or krb5-x.y-beta1 or similar for an alpha or beta release)

Running mkrel

path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z
- For an alpha or beta release, path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1 or similar
manually inspect output for versioning and correctness
- HTML docs
- PDF docs
- patchlevel.h as modified by mkrel
push release branch commits and release tags to authoritative repository
- you will need to be in hooks.branchers in the authoritative repository to push the tags

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/krb5/x.y
for alpha and beta releases:
- create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release
- symlink index.html to krb5-x.y.html in that directory
- place an entry in /mit/kerberos/dist/testing.html
- send an announcement to krbdev@mit.edu
- edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y". Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.
- skip all remaining steps
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
- check that https://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 Admin -> Custom Fields -> Version_Fixed 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 (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html 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 release entries to historical.html and old news items to oldnews.html
- update /mit/kerberos/dist/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html
- review edited web pages in a web browser and double check that release numbers and release dates have been updated
- update /mit/kerberos/krb5-x.y/doc and /mit/kerberos/krb5-x.y/index.html symlinks
- update /mit/kerberos/krb5-latest symlink if this is a major or minor release
- for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html
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"
- push this commit to the authoritative repository

@@ Line 1: / Line 1: @@
 ==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.
+Release engineering operations are currently performed on a Ubuntu 18.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
+* bison
 * build-essential
 * dejagnu
 * doxygen
+* flex
 * git
 * keyutils
 * ldap-utils
+* libcmocka-dev
 * libkeyutils-dev
 * libldap2-dev
+* liblmdb-dev
+* libresolv-wrapper
+* libsasl2-dev
 * libssl-dev
 * libtool
+* pkg-config
 * python-sphinx
 * python-cheetah
@@ Line 30: / Line 37: @@
 * 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.
+* At https://krbdev.mit.edu:444/rt/ , start a new search, add the term "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.
@@ Line 36: / Line 43: @@
 * 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.
+*** 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.  If there are merge conflicts, "git cherry-pick --continue" will not apply the log message hook, so edit the RT fields manually.
 *** Examine the commits any consider any possible interactions with changes made since the release branch.
-*** Run "make" and "make check".
+*** Run "make" and "make check".  Remember that "make check" will not work for multiple working directories concurrently on the same host.
 *** 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.
+* Consider pushing the updated release branches to a personal github fork and waiting for Github Actions 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.
+* Remove the "pullup" tag from each ticket.  This can be done in a bulk update from the search result page, or it can be done on each ticket individually from the jumbo page.
+==Creating a new release branch==
+* At https://krbdev.mit.edu:444/rt/ , go to Admin -> Custom Fields -> Target_version and add x.y and x.y-next values.  Do the same for Version_Fixed.
+* At https://krbdev.mit.edu:444/rt/ , perform a search with the following criteria:
+** Queue is krb5
+** Status is resolved
+** Version_Fixed is (no value)
+** Tags is not unsupported
+** Tags is not noresource
+** Tags is not nochange
+* Verify that the resulting list of tickets are all for changes introduced in the past development cycle, and bulk update them to have Version_Fixed x.y.
+* On the master branch, update doc/mitK5features.rst, updating the "Latest stable" and "Supported" release numbers.  Write up a list of major changes for the new release, broken down by category.  Code quality changes usually do not have associated tickets, so review the version history for commits with no RT headers.  Commit with the subject "Update features list for x.y".
+* On the master branch, update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code>.  Commit with the subject "Update config.guess, config.sub"
+* On the master branch, run "make regen".  Commit with the subject "make regen".  Push the master branch to the authoritative repository.
+* Create the new branch and push it to the authoritative repository.
+* On the new branch, update README for the new release:
+** Make sure that all x.y references are for the new version (they should be already).
+** Update any notes about transitions (such as enctype deprecations) and add new ones if necessary.
+** Include the list of major changes for the new release.
+** Include the list of tickets changed (copy-paste from https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html).
+** Copy the list of contributors from the previous release branch.
+** Add contributors from the RT tickets for the new release branch.
+** Commit with the message "Update README for krb5-x.y" and push to the authoritative repository.
+* On the master branch, update README for the next prerelease:
+** In README, update x.y references to x.(y+1), and update the list of contributors and any changes to transitional notes from the x.y branch.
+** In src/patchlevel.h, update KRB5_MINOR_RELEASE to y+1.
+** Commit with the message "Updates for krb5-x.(y+1)-prerelease" and push to the authoritative repository.
+* Update web pages
+** Create directory /mit/kerberos/dist/krb5/x.y and copy HEADER from a previous directory
+** Create directories /mit/kerberos/krb5-x.y and /mit/kerberos/krb5-x.y/RCS
 ==Preparing releases==
@@ Line 50: / Line 57: @@
 * check copyright years in project-wide stuff
-* update <code>config.guess</code> and <code>config.sub</code> from <code>git://git.savannah.gnu.org/config.git</code> (only for minor releases, not patch releases)
 * make sure you're in a build tree that's not the source tree and configured using <code>--enable-maintainer-mode</code>
-* <code>make depend</code> and commit if changed, with the commit message "make depend"
+* <code>make regen</code> and commit if there is more than just a pot file date change, with the commit message "make regen"
-* regenerate manpages: <code>(cd man && make man)</code> and commit if changed, with the commit message "Update man pages"
-* regenerate localization template <code>(cd po && make update-po)</code> 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"
+** for an alpha or beta release, set KRB5_RELTAIL to "beta1" or similar, and change KRB5_RELTAG to "krb5-x.y-beta1" or similar.
 * manually update README
 ** release dates (in major changes heading, ISO 8601 date format with hyphens)
+*** we do not have release dates for alpha or beta releases; add one when making the first final x.y release
 ** 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)
+*** minor changes = list of RT tickets fixed -- always grab a fresh list from RT when editing these!  (https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html)
 ** 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 <code>(cd man && make man)</code> and <code>(cd po && make update-po)</code> with updated patchlevel.h
+* re-run <code>make regen</code> 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 <code>(cd po && make update-po)</code> again.
 * commit the README, patchlevel-specific man page, and template changes with the subject "Update for krb5-x.y.z"
-* <code>git tag krb5-x.y.z-final</code>
+* <code>git tag krb5-x.y.z-final</code> (or <code>krb5-x.y-beta1</code> or similar for an alpha or beta release)
 ===Running mkrel===
 * <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y.z-final krb5-x.y.z</code>
+** For an alpha or beta release, <code>path_to_mkrel/mkrel --repository $YOUR_SOURCE_TREE krb5-x.y-beta1 krb5-x.y-beta1</code> or similar
 * manually inspect output for versioning and correctness
 ** HTML docs
 ** PDF docs
 ** patchlevel.h as modified by mkrel
-* push release branch commits to authoritative repository
+* push release branch commits and release tags to authoritative repository
+** you will need to be in hooks.branchers in the authoritative repository to push the tags
 ===Post-mkrel===
 * PGP sign (<code>gpg -ab krb5-x.y.z.tar.gz</code>, generates krb5-x.y.z.tar.gz.asc)
-* copy tar file and signature into /mit/kerberos/dist/x.y
+* copy tar file and signature into /mit/kerberos/dist/krb5/x.y
+* for alpha and beta releases:
+** create /mit/kerberos/krb5-x.y/krb5-x.y.html based on the first commit from a previous release
+** symlink index.html to krb5-x.y.html in that directory
+** place an entry in /mit/kerberos/dist/testing.html
+** send an announcement to krbdev@mit.edu
+** edit src/patchlevel.h, changing KRB5_RELTAIL to "beta1-postrelease" (or similar) and KRB5_RELTAG to "krb5-x.y".  Commit with the subject "Update for krb5-x.y-beta1-postrelease" or similar and push to the authoritative repository.
+** skip all remaining steps
 * 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
@@ Line 89: / Line 98: @@
 ** repeat for <code>HTML_LOGO=... make pdf</code> 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 https://krbdev.mit.edu/rt/NoAuth/krb5-x.y/fixed-x.y.z.html and .../bugs-x.y.z.html work
-** 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 Admin -> Custom Fields -> Version_Fixed and add a new one for the next patch release
-** 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
+** create /mit/kerberos/krb5-x.y/krb5-x.y.z.html and check it into RCS, using similar files as an example (for the first x.y release, update krb5-x.y.html using the previous release's krb5-x.y.html 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/index.html with the new release numbers (possibly removing out-of-service releases) and add entries to the "Recent news" section; add old release entries to historical.html and 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/index.html with new release references (possibly removing out-of-service releases); add old entries to historic.html
-** update /mit/kerberos/dist/historic.html with entries for any previously current releases which are no longer current
+** review edited web pages in a web browser and double check that release numbers and release dates have been updated
 ** 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
+** update /mit/kerberos/krb5-latest symlink if this is a major or minor release
+** for the first final krb5-x.y release, remove the entry from /mit/kerberos/dist/testing.html
 * 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"
+** push this commit to the authoritative repository

Difference between revisions of "Release engineering notes"

Latest revision as of 13:44, 6 July 2023

Contents

Release engineering environment

Pulling up changes to release branches

Creating a new release branch

Preparing releases

Pre-mkrel

Running mkrel

Post-mkrel

Navigation menu

Views

Personal tools

Navigation

Search

Tools