RELEASING

   1 Here are the steps to follow to create a new cairo release:
   2
   3 1) Ensure that there are no local, uncommitted/unpushed
   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 archives ready for distribution:
  17         cairo-X.Y.Z.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         Note that it's allowed (and perhaps recommended) to run the
  24         "make distcheck" step against an all-software X server such as
  25         Xvfb to avoid getting tripped up by any X-server-driver-specific
  26         bugs. See test/README for details
  27
  28         If you get errors about local PLT entries, you get the list of
  29         cairo entries with the error.  For each of these, a call to
  30         slim_hidden_def and slim_hidden_proto is needed in the cairo
  31         implementation in the style of other similar calls.
  32
  33         In the unfortunate case that you have to push a snapshot out
  34         (note, I said snapshot, not release) without the entire test
  35         suite passing, here's the magic env vars to set when doing
  36         'make distcheck' and 'make release-publish' that will let you
  37         get away with it.  At any cost, never ever release without
  38         (implied) distchecking.  Every time we got around it, it turned
  39         out to be a disaster.  Anyway, here's the pass code:
  40
  41                 DISPLAY= CAIRO_TEST_TARGET=" "
  42
  43 3) Fill out an entry in the NEWS file
  44
  45         Sift through the logs since the last release. This is most
  46         easily done with a command such as:
  47
  48                 git log --stat X.Y.Z..
  49
  50         where X.Y.Z is the previous release version.
  51
  52         Summarize major changes briefly in a style similar to other
  53         entries in NEWS. Take special care to note any additions in
  54         the API. These should be easy to find by noting modifications
  55         to .h files in the log command above. And more specifically,
  56         the following command will show each patch that has changed a
  57         public header file since the given version:
  58
  59                 find src/ -name '*.h' ! -name '*-private.h' ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
  60                 xargs git diff X.Y.Z.. --
  61
  62 4) Increment cairo_version_{minor|micro} in cairo-version.h:
  63
  64         If there are backward-incompatible changes in the API, stop
  65         now and don't release. Go back and fix the API instead. Cairo
  66         is intended to remain backwards-compatible as far as API.
  67
  68         So cairo_version_major will not be incremented unless we come
  69         up with a new versioning scheme to take advantage of it.
  70
  71         If there are API additions, then increment cairo_version_minor
  72         and reset cairo_version_micro to 0. NOTE: The minor version is
  73         only incremented for releases, not for snapshots.
  74
  75         Otherwise, (i.e. there are only bug fixes), increment
  76         cairo_version_micro to the next larger (even) number.
  77
  78 5) Commit the changes to NEWS and cairo-version.h
  79
  80         It's especially important to mention the new version number in your
  81         commit log.
  82
  83 6) Run "make release-publish" which will perform the following steps
  84    for you:
  85
  86         * Generate ChangeLog files out of git repository
  87         * Check that ChangeLog files were generated properly
  88         * Check that the version number ends with an even micro component
  89         * Check that no release exists with the current version
  90         * Verify that make distcheck completes successfully
  91         * Generate the final tar file
  92         * Generate an sha1sum file
  93         * Sign the sha1sum using your GPG setup (asks for your GPG password)
  94         * scp the three files to appear on http://cairographics.org/releases
  95         * Generate a versioned manual and upload it to appear as both:
  96           http://cairographics.org/manual-X.Y.Z
  97           http://cairographics.org/manual
  98         * Place local copies of the three files in the releases directory
  99         * Create a LATEST-package-version file (after deleting any old one)
 100         * Tag the entire source tree with a tag of the form X.Y.Z, and sign
 101           the tag with your GPG key (asks for your GPG password, and you
 102           may need to set GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL to match
 103           your public-key's setting or this fails.)
 104         * Provide some text for the release announcement (see below).
 105           If for some reason you lost this message, "make release-publish-message"
 106           prints it for you.
 107
 108 7) Increment cairo_version_micro to the next larger (odd) number in
 109    cairo-version.h, commit, and push.
 110
 111 8) Push the newly created tag out to the central tree with a command
 112    something like:
 113
 114         git push cairo X.Y.Z
 115
 116 9) Edit the cairo bugzilla product and add the new version numbers. Note
 117    that you need to add two versions.  One for the release/snapshot (with
 118    an even micro version), another with the post-release version (with an
 119    odd micro version).
 120
 121 10) Send a message to cairo-announce@cairographics.org and CC
 122     gnome-announce-list@gnome.org and ftp-release@lists.freedesktop.org
 123     (pr@lwn.net as well for major releases) to announce the new release
 124     using the text provided from "make release-publish", adding the excerpt
 125     from NEWS, your signature, followed by the standard "What is cairo" and
 126     "Where to get more information about cairo" blurbs from README, and
 127     finally the shortlog of all changes since last release, generated by:
 128
 129         git shortlog X.Y.Z...
 130
 131     where X.Y.Z is the last released version.
 132
 133 11) Edit the cairo wiki to add the announcement to the NEWS page and
 134     the front page. (just the parts before your signature).
 135
 136 12) For minor releases (no X.Y change), notify desktop-devel-list@gnome.org
 137     or update the ExternalDependencies page for the current cycle if you
 138     know where it is.  Currently it's:
 139
 140         http://live.gnome.org/TwoPointNineteen/ExternalDependencies