How to do a GTK+ release?

=========================

Make sure you have suitable versions of autoconf and libtool.

Also make sure you have the following packages installed with all their

dependencies:

* gtk-doc

* docbook-utils

Without those packages make distcheck will *not* pass.

Make sure that gtk-doc is the latest released version.

 0) Go back to a pristine working directory. With git, this works:

    git clean -f -x

 1) autogen and build it, make sure to enable docs by specifying

    --enable-gtk-doc --enable-man

 2) Update NEWS based on the content of git log; follow the format

    of prior entries. This includes finding noteworthy new features,

    collecting summaries for all the fixed bugs that are referenced

    and collecting all updated translations.

    Also collect the names of all contributors that are mentioned.

    We don't discriminate between bug reporters, patch writers,

    committers, etc. Anybody who is mentioned in ChangeLog gets

    credits, but only real names, not email addresses or nicknames.

 3) In particular, if this is a major, stable, release, verify that

    README.in contains the relevant release notes and that the

    required versions of dependencies in INSTALL.in are in sync

    with configure.in.

 4) Verify that the version in configure.in has been bumped after the last

    release. (Note that this is critical, a slip-up here will cause the

    soname to change).

 5) Make sure that make check is happy (If you don't do it here, make distcheck

    will also catch it, but it is kind of disheartening to see make distcheck

    fail due to an extraneous symbol after watching it build the docs for an

    hour...).

    Typical problems to expect here (depending on whether this is a devel

    snapshot or a stable release):

    * forgotten source files

    * new symbols missing from .symbols files

    * symbols that are exported by should be private (static or _-prefixed)

    * symbols that cause PLT entries. This is either caused by using

      a in the same library function without including the header or by

      using a function from a different library, which is not yet allowed

      by the filter in pltcheck.sh

 6) If this is a devel release, make sure that the docs for new symbols

    are in good shape. Look at the -unused.txt files and add stuff found

    there to the corresponding -sections.txt file. Look at the

    -undocumented.txt files and see if there is anything in there that

    should be documented. If it is, this may be due to typos in the doc

    comments in the source. Make sure that all new symbols have proper

    Since: tags, and that there is an index in the main -docs.sgml for

    the next stable version.

 7) make distcheck

 8) Fix broken stuff found by 7), repeat

 9) Commit all changes: git commit -a. You will have a bunch of po file

    changes, NEWS and maybe some doc changes too

10) Now you've got the tarball. Check that the tarball size looks

    reasonable compared to previous releases. If the size goes down

    a lot, likely the docs went missing for some reason. Or the translations.

    If the size goes up by a lot, something else may be wrong.

11) Tag the release. The git command for doing that looks like

    git tag -m "GTK+ 2.12.10" 2.12.10

12) Push the tagged commit upstream. The git command for doing that is

    git push origin refs/tags/2.12.10

13) Bump the version number in configure.in and commit and push this change

14) Upload the tarball to master.gnome.org and run install-module to transfer

    it to download.gnome.org. If you don't have an account on master.gnome.org,

    find someone who can do it for you. The command for this looks like

      scp gtk+-2.12.10.tar.gz matthiasc@master.gnome.org:

      ssh matthiasc@master.gnome.org

      install-module gtk+-2.12.10.tar.gz

15) Get the .bz2 tarball and the .md5sum files back from master.gnome.org

    You can probably also create it locally, but I've experienced md5

    mismatches when doing so.

16) Upload the .gz and .bz2 tarballs and checksums to ftp.gtk.org and put

    them in the right directory below /ftp/pub. Pay attention to correct

    ownership, and don't forget to update the LATEST file in the directory.

17) Go to the gnome-announce list archives, find the last announce message,

    create a new message in the same form, replacing version numbers,

    commentary at the top about "what this release is about" and the

    summary of changes.

18) Send it to gnome-announce-list, gtk-list, gtk-app-devel-list and

    gtk-devel-list. Set reply-to to desktop-devel-list.

19) Add a link to the release announcement to www.gtk.org which lives

    in the gtk-web git module.