doc/releasing.md

   1 # Releasing Cairo
   2
   3 Here are the steps to follow to create a new cairo release:
   4
   5 ## 0. Decide type of release and checkout the appropriate branch
   6
   7 The Cairo project makes three types of releases: Development snapshot
   8 releases, stable minor releases, and stable micro (aka "point") releases.
   9 Micro releases should be only bugfixes and no API additions.  If there are
  10 API additions consider making a Minor release.  Snapshot releases can be
  11 done of the current development tree between Minor releases, as desired.
  12
  13 For stable releases (both minor and micro), the work should be done on the
  14 given release branch.  E.g. for 1.14.12, check out the 1.14 branch via "git
  15 checkout origin/1.14 -b 1.14".
  16
  17 ## 1. Ensure that there are no local, uncommitted/unpushed mods
  18
  19 You're probably in a good state if both "git diff HEAD" and "git log
  20 master..origin/master" give no output.
  21
  22 ## 2. Verify that the code passes `meson dist`
  23
  24 First, make sure you have 'nm' and 'readelf' commands in `PATH`.  this
  25 should be OK with any Linux distro.
  26
  27 Running "meson dist" should result in no warnings or errors and end with a
  28 message of the form:
  29
  30     Created source/cairo/_build/meson-dist/cairo-1.17.8.tar.xz
  31
  32 If the test suite does not pass, you can use:
  33
  34     meson dist --no-tests
  35
  36 But this should only be allowed for development snapshots. Please, always
  37 check the state of the CI pipeline on GitLab.
  38
  39 ## 3. Decide what the new version number for the release will be.
  40
  41 Cairo uses even numbers for official releases, and odd numbers for
  42 development snapshots.  Thus, for a Minor release it would be:
  43
  44     LAST_RELEASE="X.Y.Z"     # e.g. 1.12.0
  45     THIS_RELEASE="X.Y+2.0"   # e.g. 1.14.0
  46
  47 While for a Micro release the version numbers should be:
  48
  49     LAST_RELEASE="X.Y.Z"     # e.g. 1.14.0
  50     THIS_RELEASE="X.Y.Z+2"   # e.g. 1.14.2
  51
  52 Snapshots are similar but have odd minor versions.  Also, the first snapshot
  53 release in a new series will be .2 rather than .0, e.g.:
  54
  55     LAST_RELEASE="X.Y.Z"     # e.g. 1.14.0
  56     THIS_RELEASE="X.Y+1.0"   # e.g. 1.15.2
  57
  58 and subsequent snapshots in that series are just normal micro releases:
  59
  60     LAST_RELEASE="X.Y.Z"     # e.g. 1.15.2
  61     THIS_RELEASE="X.Y.Z+2"   # e.g. 1.15.4
  62
  63 ## 4. Fill out an entry in the NEWS file
  64
  65 Sift through the logs since the last release. This is most easily done with
  66 a command such as:
  67
  68     git log --stat ${LAST_RELEASE}..
  69
  70 Summarize major changes briefly in a style similar to other entries in NEWS.
  71 Take special care to note any additions in the API. These should be easy to
  72 find by noting modifications to .h files in the log command above. And more
  73 specifically, the following command will show each patch that has changed a
  74 public header file since the given version:
  75
  76 ```
  77 find src/ -name '*.h' ! -name '*-private.h' \
  78     ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
  79     xargs git diff ${LAST_RELEASE}.. --
  80 ```
  81
  82
  83 ## 5. Increment `CAIRO_VERSION_{MINOR|MICRO}` in `src/cairo-version.h`:
  84
  85 If there are backward-incompatible changes in the API, stop now and don't
  86 release. Go back and fix the API instead. Cairo is intended to remain
  87 backwards-compatible as far as API.
  88
  89 So `CAIRO_VERSION_MAJOR` will not be incremented unless we come up with a
  90 new versioning scheme to take advantage of it.
  91
  92 If there are API additions, then increment `CAIRO_VERSION_MINOR` and reset
  93 `CAIRO_VERSION_MICRO` to 0. **NOTE**: The minor version is only incremented
  94 for releases, not for snapshots.
  95
  96 Otherwise, (i.e. there are only bug fixes), increment `CAIRO_VERSION_MICRO`
  97 to the next larger (even) number.
  98
  99 ## 6. For Minor releases, add an index entry to `doc/public/cairo-docs.xml`
 100
 101 Towards the end of the file, add a new section for the stable release.
 102 It'll look something like:
 103
 104 ```xml
 105 <index id="api-index-X-Y">
 106   <title>Index of new symbols in X.Y</title>
 107   <xi:include href="xml/api-index-X.Y.xml"/>
 108 </index>
 109 ```
 110
 111 ## 7. Commit the changes to `NEWS` and `src/cairo-version.h`
 112
 113 It's especially important to mention the new version number in your commit
 114 log.
 115
 116 ## 8. Generate the release archive
 117
 118 The `meson dist` command will:
 119
 120  * Generate the final tar file
 121  * Generate an sha1sum file
 122
 123 Once you have the release archive you will need to:
 124
 125  * Sign the sha1sum using your GPG setup (asks for your GPG password)
 126  * `scp` the three files to appear on https://cairographics.org/releases
 127  * Generate a versioned manual and upload it to appear as both:
 128    - `https://cairographics.org/manual-${THIS_RELEASE}`
 129    - `https://cairographics.org/manual`
 130  * Place local copies of the three files in the releases directory
 131  * Create a `LATEST-{package_version}` file (after deleting any old one)
 132  * Tag the entire source tree with a `${THIS_RELEASE}` tag, and sign the
 133    tag with your GPG key (asks for your GPG password, and you may need to
 134    set `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` to match your
 135    public-key's setting or this fails.)
 136  * Provide some text for the release announcement (see below).
 137
 138 ## 9. Update master (or the stable branch) version number.
 139
 140 For Micro releases (X.Y.Z+2), increment `CAIRO_VERSION_MICRO` to the next
 141 larger (odd) number in `src/cairo-version.h`.
 142
 143     DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.15.10 -> 1.15.11
 144
 145 For Minor releases (X.Y.0), increment `CAIRO_VERSION_MINOR` to the next
 146 larger (odd) number, and set `CAIRO_VERSION_MICRO` to 1.
 147
 148     DEVEL_VERSION="X.Y.Z+1"  # e.g. 1.16.0 -> 1.17.1
 149
 150 Then, commit:
 151
 152     git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}"
 153
 154 ## 9. Push the new tag out
 155
 156 Use:
 157
 158     git push --atomic origin master ${THIS_RELEASE}
 159
 160 to ensure that both the tag and the latest changes in your tree are uploaded
 161 at the same time.
 162
 163 ## 10. Send out an announcement message.
 164
 165 Send a message to cairo-announce@cairographics.org and CC
 166 cairo@cairographics.org, and ftp-release@lists.freedesktop.org (pr@lwn.net
 167 as well for major releases) to announce the release, adding the excerpt from
 168 NEWS and the shortlog of all changes since last release, generated by:
 169
 170     git shortlog ${LAST_RELEASE}...
 171
 172 ## 11. Add the announcement to the website
 173
 174 Add a new entry in the `news` directory.  It will automatically get indexed
 175 onto the homepage when the site refreshes.