RELEASING

   1 Here are the steps to follow to create a new cairo release:
   2
   3 1) Ensure that there are no local, uncommitted/unspushed
   4    modifications. You're probably in a good state if both "git diff
   5    HEAD" and "git log master..origin/master" give no output.
   6
   7 2) Verify that the code passes "make distcheck"
   8
   9         First, make sure you have 'nm' and 'readelf' commands in PATH.
  10         this should be Ok with any Linux distro.
  11
  12         Running "make distcheck" should result in no warnings or
  13         errors and end with a message of the form:
  14
  15         ==================================================
  16         cairo-X.Y.Z-head archives ready for distribution:
  17         cairo-X.Y.Z-head.tar.gz
  18         ==================================================
  19
  20         (But the tar file isn't actually ready yet, as we still have
  21         some more steps to follow).
  22
  23         If you get errors about local PLT entries, you get the list of
  24         cairo and pixman entries with the error.  For each of these, a
  25         call to slim_hidden_def and slim_hidden_proto is needed in the
  26         cairo or pixman implementation in the style of other similar calls.
  27
  28 3) Fill out an entry in the NEWS file
  29
  30         Sift through the logs since the last release. This is most
  31         easily done with a comand such as:
  32
  33                 git log --stat X.Y.Z..
  34
  35         where X.Y.Z is the previous release version.
  36
  37         Summarize major changes briefly in a style similar to other
  38         entries in NEWS. Take special care to note any additions in
  39         the API. These should be easy to find by noting modifications
  40         to .h files in the log command above. And more specifically,
  41         the following command will show each patch that has changed a
  42         public header file since the given version:
  43
  44                 find src/ -name '*.h' ! -name '*-private.h' ! -name 'cairoint.h' | \
  45                 xargs git log -p X.Y.Z.. --
  46
  47 4) Increment cairo_version_{minor|micro} and LT_{CURRENT|VERSION|AGE}
  48    in configure.in:
  49
  50         If there are backward-incompatible changes in the API, stop
  51         now and don't release. Go back and fix the API instead. Cairo
  52         is intended to remain backwards-compatible as far as API.
  53
  54         So cairo_version_major will not be incremented unless we come
  55         up with a new versioning scheme to take advantage of it.
  56
  57         If there are API additions, then increment cairo_version_minor
  58         and reset cairo_version_micro to 0. NOTE: The minor version is
  59         only incremented for releases, not for snapshots.
  60
  61         Otherwise, (ie. there are only bug fixes), increment
  62         cairo_version_micro to the next larger (even) number.
  63
  64         Adjust LT_CURRENT, LT_VERSION, and LT_AGE as described in the
  65         comments in configure.in.
  66
  67 5) Commit the changes to NEWS and configure.in
  68
  69         It's especially important to mention the new version number in your
  70         commit log.
  71
  72 6) Run "make release-publish" which will perform the following steps
  73    for you:
  74
  75         * Generate ChangeLog files out of git repository
  76         * Check that ChangeLog files were generated properly
  77         * Check that the version number ends with an even micro component
  78         * Check that no release exists with the current version
  79         * Verify that make distcheck completes successfully
  80         * Generate the final tar file
  81         * Generate an sha1sum file
  82         * Sign the sha1sum using your GPG setup (asks for your GPG password)
  83         * scp the three files to appear on http://cairographics.org/releases
  84         * Place local copies of the three files in the releases directory
  85         * Create a LATEST-package-version file (after deleting any old one)
  86         * Tag the entire source tree with a tag of the form X.Y.Z, and sign
  87           the tag with your GPG key (asks for your GPG password, and you
  88           may need to set GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL to match
  89           your public-key's setting or this fails.)
  90         * Provide some text for the release announcement (see below).
  91           If for some reason you lost this message, "make release-publish-message"
  92           prints it for you.
  93
  94 7) Increment cairo_version_micro to the next larger (odd) number in
  95    configure, commit, and push.
  96
  97 8) Push the newly created tag out to the central tree with a command
  98    something like:
  99
 100         git push cairo X.Y.Z
 101
 102 9) Edit the cairo bugzilla product and add the new version numbers. Note
 103    that you need to add two versions.  One for the release/snapshot (with
 104    an even micro version), another with the post-release version (with an
 105    odd micro version).
 106
 107 10) Send a message to cairo-announce@cairographics.org and CC
 108     gnome-announce-list@gnome.org, (pr@lwn.net as well for major
 109     releases) to announce the new release using the text provided from
 110     "make release-publish", adding the excerpt from NEWS, your
 111     signature, followed by the standard "What is cairo" and "Where to
 112     get more information about cairo" blurbs from README, and finally
 113     tacking on the detailed changelog-ish thing that gets mailed out
 114     when you push the tag (but not the diffstat thing).
 115
 116 11) Edit the cairo wiki to add the announcement to the NEWS page and
 117     the front page. (just the parts before your signature).
 118
 119 12) For minor releases (no X.Y change), notify desktop-devel-list@gnome.org
 120     or update the ExternalDependencies page for the current cycle if you
 121     know where it is.  Currently it's:
 122
 123         http://live.gnome.org/TwoPointNineteen/ExternalDependencies