From d86a22db6d512b344a61843107f888d6f12c98fe Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Mon, 30 Jan 2023 15:12:42 +0000 Subject: docs: Update the release instruction Mainly drop the Autotools-related stuff, and use Markdown. --- doc/releasing.md | 272 ++++++++++++++++++++++++------------------------------- 1 file changed, 116 insertions(+), 156 deletions(-) (limited to 'doc') diff --git a/doc/releasing.md b/doc/releasing.md index 04c78e20a..ab5abb62b 100644 --- a/doc/releasing.md +++ b/doc/releasing.md @@ -1,215 +1,175 @@ -Here are the steps to follow to create a new cairo release: +# Releasing Cairo -0) Decide type of release and checkout the appropriate branch. +Here are the steps to follow to create a new cairo release: - The Cairo project makes three types of releases: Development - snapshot releases, stable minor releases, and stable micro (aka - "point") releases. Micro releases should be only bugfixes and - no API additions. If there are API additions consider making a - Minor release. Snapshot releases can be done of the current - development tree between Minor releases, as desired. +## 0. Decide type of release and checkout the appropriate branch - For stable releases (both minor and micro), the work should be - done on the given release branch. E.g. for 1.14.12, check out - the 1.14 branch via "git checkout origin/1.14 -b 1.14". +The Cairo project makes three types of releases: Development snapshot +releases, stable minor releases, and stable micro (aka "point") releases. +Micro releases should be only bugfixes and no API additions. If there are +API additions consider making a Minor release. Snapshot releases can be +done of the current development tree between Minor releases, as desired. -1) Ensure that there are no local, uncommitted/unpushed mods. +For stable releases (both minor and micro), the work should be done on the +given release branch. E.g. for 1.14.12, check out the 1.14 branch via "git +checkout origin/1.14 -b 1.14". - You're probably in a good state if both "git diff - HEAD" and "git log master..origin/master" give no output. Also make - sure you have libglib2.0-doc installed (else you'll get - excessive gtk-doc cross reference warnings in the next step). +## 1. Ensure that there are no local, uncommitted/unpushed mods -2) Verify that the code passes "make distcheck" +You're probably in a good state if both "git diff HEAD" and "git log +master..origin/master" give no output. - First, make sure you have 'nm' and 'readelf' commands in PATH. - this should be OK with any Linux distro. +## 2. Verify that the code passes `meson dist` - Running "make distcheck" should result in no warnings or - errors and end with a message of the form: +First, make sure you have 'nm' and 'readelf' commands in `PATH`. this +should be OK with any Linux distro. - ============================================= - cairo-X.Y.Z archives ready for distribution: - cairo-X.Y.Z.tar.gz - ============================================= +Running "meson dist" should result in no warnings or errors and end with a +message of the form: - (But the tar file isn't actually ready yet, as we still have - some more steps to follow). + Created source/cairo/_build/meson-dist/cairo-1.17.8.tar.xz - Note that it's allowed (and perhaps recommended) to run the - "make distcheck" step against an all-software X server such as - Xvfb to avoid getting tripped up by any X-server-driver-specific - bugs. See test/README for details +If the test suite does not pass, you can use: - If you get errors about local PLT entries, you get the list of - cairo entries with the error. For each of these, a call to - slim_hidden_def and slim_hidden_proto is needed in the cairo - implementation in the style of other similar calls. + meson dist --no-tests - In the unfortunate case that you have to push a snapshot out - (note, I said snapshot, not release) without the entire test - suite passing, here's the magic env vars to set when doing - 'make distcheck' and 'make release-publish' that will let you - get away with it. At any cost, never ever release without - (implied) distchecking. Every time we got around it, it turned - out to be a disaster. Anyway, here's the pass code: +But this should only be allowed for development snapshots. Please, always +check the state of the CI pipeline on GitLab. - DISPLAY= CAIRO_TEST_TARGET=" " +## 3. Decide what the new version number for the release will be. -3) Decide what the new version number for the release will be. +Cairo uses even numbers for official releases, and odd numbers for +development snapshots. Thus, for a Minor release it would be: - Cairo uses even numbers for official releases, and odd numbers - for development snapshots. Thus, for a Minor release it would - be: + LAST_RELEASE="X.Y.Z" # e.g. 1.12.0 + THIS_RELEASE="X.Y+2.0" # e.g. 1.14.0 - LAST_RELEASE="X.Y.Z" # e.g. 1.12.0 - THIS_RELEASE="X.Y+2.0" # e.g. 1.14.0 +While for a Micro release the version numbers should be: - While for a Micro release the version numbers should be: + LAST_RELEASE="X.Y.Z" # e.g. 1.14.0 + THIS_RELEASE="X.Y.Z+2" # e.g. 1.14.2 - LAST_RELEASE="X.Y.Z" # e.g. 1.14.0 - THIS_RELEASE="X.Y.Z+2" # e.g. 1.14.2 +Snapshots are similar but have odd minor versions. Also, the first snapshot +release in a new series will be .2 rather than .0, e.g.: - Snapshots are similar but have odd minor versions. Also, the - first snapshot release in a new series will be .2 rather than - .0, e.g.: + LAST_RELEASE="X.Y.Z" # e.g. 1.14.0 + THIS_RELEASE="X.Y+1.0" # e.g. 1.15.2 - LAST_RELEASE="X.Y.Z" # e.g. 1.14.0 - THIS_RELEASE="X.Y+1.0" # e.g. 1.15.2 +and subsequent snapshots in that series are just normal micro releases: - and subsequent snapshots in that series are just normal micro - releases: + LAST_RELEASE="X.Y.Z" # e.g. 1.15.2 + THIS_RELEASE="X.Y.Z+2" # e.g. 1.15.4 - LAST_RELEASE="X.Y.Z" # e.g. 1.15.2 - THIS_RELEASE="X.Y.Z+2" # e.g. 1.15.4 +## 4. Fill out an entry in the NEWS file -4) Fill out an entry in the NEWS file +Sift through the logs since the last release. This is most easily done with +a command such as: - Sift through the logs since the last release. This is most - easily done with a command such as: + git log --stat ${LAST_RELEASE}.. - git log --stat ${LAST_RELEASE}.. +Summarize major changes briefly in a style similar to other entries in NEWS. +Take special care to note any additions in the API. These should be easy to +find by noting modifications to .h files in the log command above. And more +specifically, the following command will show each patch that has changed a +public header file since the given version: - Summarize major changes briefly in a style similar to other - entries in NEWS. Take special care to note any additions in - the API. These should be easy to find by noting modifications - to .h files in the log command above. And more specifically, - the following command will show each patch that has changed a - public header file since the given version: +``` +find src/ -name '*.h' ! -name '*-private.h' \ + ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \ + xargs git diff ${LAST_RELEASE}.. -- +``` - find src/ -name '*.h' ! -name '*-private.h' \ - ! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \ - xargs git diff ${LAST_RELEASE}.. -- - Include a link to the incremental ChangeLog for this release, - which we'll be uploading in a later step: +## 5. Increment `CAIRO_VERSION_{MINOR|MICRO}` in `src/cairo-version.h`: - https://cairographics.org/releases/ChangeLog.cairo-${THIS_RELEASE} +If there are backward-incompatible changes in the API, stop now and don't +release. Go back and fix the API instead. Cairo is intended to remain +backwards-compatible as far as API. -4) Increment cairo_version_{minor|micro} in src/cairo-version.h: +So `CAIRO_VERSION_MAJOR` will not be incremented unless we come up with a +new versioning scheme to take advantage of it. - If there are backward-incompatible changes in the API, stop - now and don't release. Go back and fix the API instead. Cairo - is intended to remain backwards-compatible as far as API. +If there are API additions, then increment `CAIRO_VERSION_MINOR` and reset +`CAIRO_VERSION_MICRO` to 0. **NOTE**: The minor version is only incremented +for releases, not for snapshots. - So cairo_version_major will not be incremented unless we come - up with a new versioning scheme to take advantage of it. +Otherwise, (i.e. there are only bug fixes), increment `CAIRO_VERSION_MICRO` +to the next larger (even) number. - If there are API additions, then increment cairo_version_minor - and reset cairo_version_micro to 0. NOTE: The minor version is - only incremented for releases, not for snapshots. +## 6. For Minor releases, add an index entry to `doc/public/cairo-docs.xml` - Otherwise, (i.e. there are only bug fixes), increment - cairo_version_micro to the next larger (even) number. +Towards the end of the file, add a new section for the stable release. +It'll look something like: -5) For Minor releases, add an index entry to doc/public/cairo-docs.xml +```xml + + Index of new symbols in X.Y + + +``` - Towards the end of the file, add a new section for the stable - release. It'll look something like: +## 7. Commit the changes to `NEWS` and `src/cairo-version.h` - - Index of new symbols in X.Y - +It's especially important to mention the new version number in your commit +log. -6) Commit the changes to NEWS and src/cairo-version.h +## 8. Generate the release archive - It's especially important to mention the new version number in your - commit log. +The `meson dist` command will: -7) Run "make release-publish" which will perform the following steps - for you: + * Generate the final tar file + * Generate an sha1sum file - * Generate ChangeLog files out of git repository - * Check that ChangeLog files were generated properly - * Check that the version number ends with an even micro component - * Check that no release exists with the current version - * Verify that make distcheck completes successfully - * Generate the final tar file - * Generate an sha1sum file - * Sign the sha1sum using your GPG setup (asks for your GPG password) - * scp the three files to appear on https://cairographics.org/releases - * Generate a versioned manual and upload it to appear as both: - https://cairographics.org/manual-${THIS_RELEASE} - https://cairographics.org/manual - * Place local copies of the three files in the releases directory - * Create a LATEST-package-version file (after deleting any old one) - * Tag the entire source tree with a ${THIS_RELEASE} tag, and sign - the tag with your GPG key (asks for your GPG password, and you - may need to set GIT_COMMITTER_NAME and GIT_COMMITTER_EMAIL to match - your public-key's setting or this fails.) - * Provide some text for the release announcement (see below). - If for some reason you lost this message, "make release-publish-message" - prints it for you. +Once you have the release archive you will need to: - Upload the incremental ChangeLog generated by the above. For - minor stable releases, this is: + * Sign the sha1sum using your GPG setup (asks for your GPG password) + * `scp` the three files to appear on https://cairographics.org/releases + * Generate a versioned manual and upload it to appear as both: + - `https://cairographics.org/manual-${THIS_RELEASE}` + - `https://cairographics.org/manual` + * Place local copies of the three files in the releases directory + * Create a `LATEST-{package_version}` file (after deleting any old one) + * Tag the entire source tree with a `${THIS_RELEASE}` tag, and sign the + tag with your GPG key (asks for your GPG password, and you may need to + set `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` to match your + public-key's setting or this fails.) + * Provide some text for the release announcement (see below). - scp ChangeLog \ - cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE} +## 9. Update master (or the stable branch) version number. - for micro and snapshot releases, the command is: +For Micro releases (X.Y.Z+2), increment `CAIRO_VERSION_MICRO` to the next +larger (odd) number in `src/cairo-version.h`. - scp ChangeLog.cache-${LAST_RELEASE}.. \ - cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE} + DEVEL_VERSION="X.Y.Z+1" # e.g. 1.15.10 -> 1.15.11 - To undo a release-publish, before you've sent any emails or - pushed changes to master, delete the locally created tag (git - tag -d ${THIS_RELEASE}); then log into the webserver, repoint - the manual and LATEST-cairo-${THIS_RELEASE} symlinks to the - previous versions, remove manual-${THIS_RELEASE} and - release/cairo-${THIS_RELEASE}. +For Minor releases (X.Y.0), increment `CAIRO_VERSION_MINOR` to the next +larger (odd) number, and set `CAIRO_VERSION_MICRO` to 1. -8) Push the new tag out to the central tree with a command like: + DEVEL_VERSION="X.Y.Z+1" # e.g. 1.16.0 -> 1.17.1 - git push origin master ${THIS_RELEASE} +Then, commit: -9) Update master (or the stable branch) version number. + git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}" - For Micro releases (X.Y.Z+2), increment cairo_version_micro to - the next larger (odd) number in src/cairo-version.h, commit, and - push. +## 9. Push the new tag out - DEVEL_VERSION="X.Y.Z+1" # e.g. 1.15.10 -> 1.15.11 +Use: - For Minor releases (X.Y.0), increment cairo_version_minor to the - next larger (odd) number, and set cairo_version_micro to 1. Then - commit and push. + git push --atomic origin master ${THIS_RELEASE} - DEVEL_VERSION="X.Y.Z+1" # e.g. 1.16.0 -> 1.17.1 +to ensure that both the tag and the latest changes in your tree are uploaded +at the same time. - git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}" +## 10. Send out an announcement message. -10) Send out an announcement message. +Send a message to cairo-announce@cairographics.org and CC +cairo@cairographics.org, and ftp-release@lists.freedesktop.org (pr@lwn.net +as well for major releases) to announce the release, adding the excerpt from +NEWS and the shortlog of all changes since last release, generated by: - Send a message to cairo-announce@cairographics.org and CC - cairo@cairographics.org, gnome-announce-list@gnome.org and - ftp-release@lists.freedesktop.org (pr@lwn.net as well for major - releases) to announce the new release using the text provided from - "make release-publish", adding the excerpt from NEWS and - the shortlog of all changes since last release, generated by: + git shortlog ${LAST_RELEASE}... - git shortlog ${LAST_RELEASE}... +## 11. Add the announcement to the website -11) Add the announcement to the website as a new entry in the news/ - dir. It will automatically get indexed onto the homepage when the - site refreshes. +Add a new entry in the `news` directory. It will automatically get indexed +onto the homepage when the site refreshes. -- cgit v1.2.1