fdo-mirrors/cairo
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/cairo/cairo.git synced 2026-05-05 22:48:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Update the release instruction

Browse source 
Mainly drop the Autotools-related stuff, and use Markdown.
This commit is contained in:
Emmanuele Bassi 2023-01-30 15:12:42 +00:00
parent d54e908c98
commit d86a22db6d
1 changed files with 116 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

272
doc/releasing.md
View file

@ -1,215 +1,175 @@
# Releasing Cairo
Here are the steps to follow to create a new cairo release:
0) Decide type of release and checkout the appropriate branch.
## 0. Decide type of release and checkout the appropriate branch
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.
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.
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".
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".
1) Ensure that there are no local, uncommitted/unpushed mods.
## 1. Ensure that there are no local, uncommitted/unpushed mods
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).
You're probably in a good state if both "git diff HEAD" and "git log
master..origin/master" give no output.
2) Verify that the code passes "make distcheck"
## 2. Verify that the code passes `meson dist`
First, make sure you have 'nm' and 'readelf' commands in PATH.
this should be OK with any Linux distro.
First, make sure you have 'nm' and 'readelf' commands in `PATH`. this
should be OK with any Linux distro.
Running "make distcheck" should result in no warnings or
errors and end with a message of the form:
Running "meson dist" should result in no warnings or errors and end with a
message of the form:
=============================================
cairo-X.Y.Z archives ready for distribution:
cairo-X.Y.Z.tar.gz
=============================================
Created source/cairo/_build/meson-dist/cairo-1.17.8.tar.xz
(But the tar file isn't actually ready yet, as we still have
some more steps to follow).
If the test suite does not pass, you can use:
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
meson dist --no-tests
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.
But this should only be allowed for development snapshots. Please, always
check the state of the CI pipeline on GitLab.
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:
## 3. Decide what the new version number for the release will be.
DISPLAY= CAIRO_TEST_TARGET=" "
Cairo uses even numbers for official releases, and odd numbers for
development snapshots. Thus, for a Minor release it would be:
3) Decide what the new version number for the release will be.
LAST_RELEASE="X.Y.Z" # e.g. 1.12.0
THIS_RELEASE="X.Y+2.0" # e.g. 1.14.0
Cairo uses even numbers for official releases, and odd numbers
for development snapshots. Thus, for a Minor release it would
be:
While for a Micro release the version numbers should 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.14.0
THIS_RELEASE="X.Y.Z+2" # e.g. 1.14.2
While for a Micro release the version numbers should be:
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.Z+2" # e.g. 1.14.2
LAST_RELEASE="X.Y.Z" # e.g. 1.14.0
THIS_RELEASE="X.Y+1.0" # e.g. 1.15.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.:
and subsequent snapshots in that series are just normal micro releases:
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.15.2
THIS_RELEASE="X.Y.Z+2" # e.g. 1.15.4
and subsequent snapshots in that series are just normal micro
releases:
## 4. Fill out an entry in the NEWS file
LAST_RELEASE="X.Y.Z" # e.g. 1.15.2
THIS_RELEASE="X.Y.Z+2" # e.g. 1.15.4
Sift through the logs since the last release. This is most easily done with
a command such as:
4) Fill out an entry in the NEWS file
git log --stat ${LAST_RELEASE}..
Sift through the logs since the last release. This is most
easily done with a command such as:
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:
git log --stat ${LAST_RELEASE}..
```
find src/ -name '*.h' ! -name '*-private.h' \
! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
xargs git diff ${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:
find src/ -name '*.h' ! -name '*-private.h' \
! -name 'cairoint.h' ! -name 'cairo-*features*.h' | \
xargs git diff ${LAST_RELEASE}.. --
## 5. Increment `CAIRO_VERSION_{MINOR|MICRO}` in `src/cairo-version.h`:
Include a link to the incremental ChangeLog for this release,
which we'll be uploading in a later step:
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.
https://cairographics.org/releases/ChangeLog.cairo-${THIS_RELEASE}
So `CAIRO_VERSION_MAJOR` will not be incremented unless we come up with a
new versioning scheme to take advantage of it.
4) Increment cairo_version_{minor|micro} in src/cairo-version.h:
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.
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.
Otherwise, (i.e. there are only bug fixes), increment `CAIRO_VERSION_MICRO`
to the next larger (even) number.
So cairo_version_major will not be incremented unless we come
up with a new versioning scheme to take advantage of it.
## 6. For Minor releases, add an index entry to `doc/public/cairo-docs.xml`
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.
Towards the end of the file, add a new section for the stable release.
It'll look something like:
Otherwise, (i.e. there are only bug fixes), increment
cairo_version_micro to the next larger (even) number.
```xml
<index id="api-index-X-Y">
<title>Index of new symbols in X.Y</title>
<xi:include href="xml/api-index-X.Y.xml"/>
</index>
```
5) For Minor releases, add an index entry to doc/public/cairo-docs.xml
## 7. Commit the changes to `NEWS` and `src/cairo-version.h`
Towards the end of the file, add a new section for the stable
release. It'll look something like:
It's especially important to mention the new version number in your commit
log.
<index id="index-X.Y" role="X.Y">
<title>Index of new symbols in X.Y</title>
</index>
## 8. Generate the release archive
6) Commit the changes to NEWS and src/cairo-version.h
The `meson dist` command will:
It's especially important to mention the new version number in your
commit log.
* Generate the final tar file
* Generate an sha1sum file
7) Run "make release-publish" which will perform the following steps
for you:
Once you have the release archive you will need to:
* 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.
* 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).
Upload the incremental ChangeLog generated by the above. For
minor stable releases, this is:
## 9. Update master (or the stable branch) version number.
scp ChangeLog \
cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.cairo-${THIS_RELEASE}
For Micro releases (X.Y.Z+2), increment `CAIRO_VERSION_MICRO` to the next
larger (odd) number in `src/cairo-version.h`.
for micro and snapshot releases, the command is:
DEVEL_VERSION="X.Y.Z+1" # e.g. 1.15.10 -> 1.15.11
scp ChangeLog.cache-${LAST_RELEASE}.. \
cairographics.org:/srv/cairo.freedesktop.org/www/releases/ChangeLog.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.
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}.
DEVEL_VERSION="X.Y.Z+1" # e.g. 1.16.0 -> 1.17.1
8) Push the new tag out to the central tree with a command like:
Then, commit:
git push origin master ${THIS_RELEASE}
git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}"
9) Update master (or the stable branch) version number.
## 9. Push the new tag out
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.
Use:
DEVEL_VERSION="X.Y.Z+1" # e.g. 1.15.10 -> 1.15.11
git push --atomic origin master ${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. Then
commit and push.
to ensure that both the tag and the latest changes in your tree are uploaded
at the same time.
DEVEL_VERSION="X.Y.Z+1" # e.g. 1.16.0 -> 1.17.1
## 10. Send out an announcement message.
git commit src/cairo-version.h -m "Bump version for ${DEVEL_VERSION}"
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:
10) Send out an announcement message.
git shortlog ${LAST_RELEASE}...
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:
## 11. Add the announcement to the website
git shortlog ${LAST_RELEASE}...
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.