gstreamer/docs/random/release

GStreamer Release Policies (or: why we should become a country and pass laws)
--------------------------

Development Period
------------------
Development period is marked by having a fourth (nano) version number of 1.
During development anything goes short of wiping the tree.
Just try doing a few basic things :
- make sure it builds for you !
- check what you're about to commit with cvs -Q diff -r
- preferably, keep an anonymous checkout around as well so you can
  immediately update and check if your changes work in a clean tree as well

Prerelease Period
-----------------
After a bit of development, people want a new release.  This generally happens
when :
- core developers get anxious to apply massive changes to the core bound
  to break everything
- a few important plugins decide, as if by magic, to work again (avi, mad, ...)
- thaytan or thomasvs get tired of being lazy.

Also, this should only be allowed after passing a few sanity checks :
- make distcheck should pass
- rpms should build
- FIXME: should debs be built here ? If so, how ?

At this time, we need to do a few prereleases for general checking by all
interested developers.  To minimize the impact on the rest of the core hacking,
we create a new CVS branch which will go through the pre-releases and finally
contain the definitive tarball for that version.

RELEASE PROCEDURE:
-----------------

- www/bin/new-release is a release helper script.  It automates a lot of the
  tedious work.  Now releasing looks like this:

- before release:
  - make sure all blocker bugs for that release are fixed or deferred
  - make sure you have a local copy of all online files
  - run 'make download-po' to make sure translations in CVS are up-to-date,
    and then 'make update' in po/ (which will update the .pot template too and
    merge the changes into the .po files)
  - Make one or more prereleases
    - Make sure you've got the latest clean CVS of the module
    - Run bin/data-get in www/ to sync data from website
    - Bump the nano number to > 2 (eg, first pre-release for 
      0.10.12 is 0.10.11.2)
    - Re-autogen if not in maintainer-mode (which you should be)
    - run 'make release' to build the tarballs
    - copy tarballs+md5 sums to the data/src/$module/pre/ dir
    - Run bin/data-put in www/ to sync the new tarballs to the website
    - Announce the availability of the new tarballs
    - Tell the translation project by sending an email to 
      coordinator@translationproject.org, eg:
        Subject: gst-plugins-bad-0.10.5.2.pot available
        Tarball is at http://gstreamer.freedesktop.org/src/gst-plugins-bad/pre/gst-plugins-bad-0.10.5.2.tar.bz2 
      FIXME: Not sure if the translation project bot parses version strings 
      with a nano correctly.

  - bin/new-release (module) (version) (checkoutdir) (release name)
    - updates cvs
    - allows you to update versioning in configure.ac
    - rebuilds
    - updates ChangeLog
    - adds a new releases/module/version.xml file and lets you edit
      --> here you add/fix up the features (from ChangeLog) and check
	  contributors
    - allows you to update NEWS file with snippets from RELEASE
      --> copy stuff
    - rebuilds docs for plugins
    - rolls release tarballs and puts them in the local www/data tree
    - uploads docs to website
    - commits changes to po files
    - shows you a diff for evaluation

  - build packages to test

- release:
  - Update the doap file to insert the new release info
  - cvs commit in the tree
  - tag tree
    for example for 0.6.3 :
           cvs tag RELEASE-0_6_3
  - bump nano number in configure.ac, commit
  - if working in the "stable" release branch, update to this tag to freeze it:
    cvs up -r RELEASE-0_6_3
  - sync source and packages to website
    + run /bin/data-put in www
  - change versions in www/src/htdocs/entities.gst
  - add entry on website
    + Edit src/htdocs/news/news.xml and add a new item at the bottom.
  - commit additions to website
  - add versions and milestones in bugzilla
  - upload new tarballs to gnome ftp
    + e.g:
       scp gstreamer-0.10.42.tar.gz master.gnome.org:
       ssh master.gnome.org
       install-module gstreamer-0.10.42.tar.gz

  - Send release announcements to:
    gstreamer-devel@lists.sourceforge.net gstreamer-announce@lists.sourceforge.net kde-multimedia@kde.org gnome-multimedia@gnome.org
  - Update freshmeat with new releases (get Uraeus to do it)

Old release notes - superseded by the www/bin/new-release script.
----------------------------------------------------------------

TODO :
  - Decide on the next version number (major, minor or micro upgrade ?)
  - Get a fresh copy to do the necessary tests on
  - If this isn't on the stable branch (like for 0.6), then create a new branch;
    - with 0.3.3 as an example, tag is BRANCH-RELEASE-0_3_3
      cvs tag BRANCH-RELEASE-0_3_3-ROOT
      cvs tag -b BRANCH-RELEASE-0_3_3
    - update your local copy to the branch:
      cvs update -r BRANCH-RELEASE-0_3_3
  - Set the nano to 2 (in configure.ac, AS_VERSION)
  - If this is a release candidate for a new major version, override
    MAJOR/MINOR in configure.ac
  - Do all updates/patches/changes for the release tarball in this branch
  - Think of a good codename for the release
  - Check the bug lists:
    - The idea is to have all bugs for this milestone listed as fixed
    - Check all of the bug reports with this version as a milestone, and verify
      that these bugs are fixed, or reassign to a later milestone if not
    - Check later milestone bugs, and if any of them are fixed, reassign to
      this milestone
    - Check the list of bugs resolved with milestone HEAD, which should be
      assigned to an actual milestone
  - create a new $(version).xml file in www/src/htdocs/releases/$(module)
    and add that to cvs
  - Start updating the release notes on the www cvs tree
    - create the base xml file in www/htdocs/releases/$/module)/$(version).xml
    - grepping ChangeLog for contributors:
 grep "<.*>" ChangeLog | perl -i -p -e 's@\d*-\d*-\d*\s*(.*)\s*<.*$@$1@' | sort | uniq
    - use www/bin/bugzilla (module) (version) to get an xml list of the
      bugs fixed in this version, and add it to the release .xml
  - depending on how the API has changed update the libtool versioning
    in configure.ac, AS_LIBTOOL 
    (Look at the libtool info page about versioning for guidelines)
    (if MAJOR/MINOR version has changed, however, you can reset all to 0)
  - FIXME: autotools have latest config.{guess,sub}
           This is needed in order to support newer platforms.
           On Debian install the autotools-dev package to get these.
           Someone please add some more useful info here on how to do this
  - while (IS_PRERELEASE)
    {
      - increase the nano number (starting with 2)
      - check out a fresh anonymous copy
        cvs -d:pserver:anonymous@cvs.gstreamer.sf.net:/cvsroot/gstreamer \
            co -rBRANCH-RELEASE-0_3_3 gstreamer
      - make distcheck, rpm build should pass, from a FRESH cvs tree
      - media tests should be done
      - source tarball should be installed and tested
      - rpms should be installed and tested
      - .2 tarball should be submitted to translation project
      - put up tarball for a day
    }


Release Period
--------------
When we're satisfied with the prereleases, it's time to make the final tarball.
It's very important that the tarball we put out is fully checked, works as
planned, and generally is generated only ONCE by someone with a relatively
clean (and reference) system.  We don't want to put out more than one tarball
with the same name.

TODO :
  - give the latest prerelease another good testing
  - proofread the release notes
  - run bugzilla with the correct module and milestone and include
    the output in the release notes
    bin/bugzilla gstreamer 0.7.5 >> src/htdocs/releases/gstreamer/0.7.5.xml
    then edit it
  - verify all new translations are in and po files are updated:
    run 'make download-po' to make sure translations in CVS are up-to-date,
    and then 'make update' in po/ (which will update the .pot template too and
    merge the changes into the .po files)
  - run win32-update from toplevel to copy new versions and enum files
  - copy  www/htdocs/releases/$(module)/$(version) to RELEASE
  - copy the list of changes, bugs fixed, and API changes and add them to NEWS
  - update the ChangeLog to account for NEWS, RELEASE, and configure.ac,
    mentioning the release name
  -  add === release (version) === to ChangeLog
  - update web site docs
    - release-specific docs should go in CVS
    - change docs/current symlink
  - remove the nano version number in configure.ac, AS_VERSION
  - cvs commit
  - tag tree
    for example for 0.6.3 :
           cvs tag RELEASE-0_6_3
  - run "make release", build rpms
  - install on gnome's ftp
  - for plugins docs: run "make update" in docs/plugins to update version info
  - for docs: run "make upload" from gstreamer/docs to get the new docs online
  - change www/src/htdocs/entities.gst with the new version numbers
  - change www/src/htdocs/bugs/bugs.xml and add a new milestone
  - possibly add new version and milestone to bugzilla
  - add a news item to the news.xml

Post-Release Period
-------------------
Time to bring the new version under the eyes of the public.

TODO :
  - FIXME: should we md5 the tarballs?
  - upload to sourceforge
      upload.sourceforge.net/incoming
      administer the release

  - FIXME: announcements
    - gstreamer-{devel, announce} : a simple mail with RELEASE
    - freshmeat
    - linux-audio-dev (if it's a big release) : a simple mail with RELEASE
    - gnome lists (?)
    - lwn (if it's a big release)
  - send mail for translators with URL to .tar.bz2:
    translation@iro.umontreal.ca 
  - Kick back, have a party, enjoy people coming in on IRC telling us how
    GStreamer rocks.
  - Later on, if necessary, merge back latest release branch to current dev
    branch (if patches to source were made)

    TWO WAYS:
    A)
       * get a diff between the branch root and the final release:
         cvs diff -r BRANCH-RELEASE-0_7_5-ROOT -r RELEASE-0_7_5 > patch
       * fix up this patch (remove RELEASE)
       * and apply it to the HEAD branch
       * update nano version to 1 in configure.ac
                                                                                
    B)
       * change to a HEAD branch, make sure it's updated
       * cvs diff -R -r RELEASE-0_3_4-30SECONDFRENCHMAN
         gives a list of differences between head and release tag,
         stuff with > is how it's in HEAD, < is in the rel branch

       * cvs update -j BRANCH-RELEASE-0_3_4
         merges the difference made in that branch to the current source
         this is what you want to use when merging back the branch
         resolve conflicts and commit

Some various random comments that might or might not make sense :

- Should work:
  * autoconf feature to allow building outside source dir

- Package version policy
  - Use major.minor.micro versioning
  - Before 1.0.0, Update micro until code and API are fairly stable,
    then update minor.
  - After 1.0.0,
    Update major when code and api hit new level of stability or major features.
    Update minor on API changes.
    Update micro on API-compatible changes.

NOTES ON STARTING A NEW STABLE SERIES
-------------------------------------
- Given x.y.z being the last devel release, where y is an odd number
- all API/ABI/renaming changes should be done
- for every module:
  - get a completely fresh checkout
  - set GST_MAJORMINOR to x.(y + 1)
  - reset libtool versioning to 0, 0, 0
  - build every piece
  - grep for possible non-updates of MAJORMINOR:
    grep -r "0\.9" * | grep -v "0\.9\.6" | less -R
    change stuff:
    perl -i -p -e 's@0\.9(\.[^0-9])@0.10$1@g' (file) changes 0.9. -> 0.10.
    perl -i -p -e 's@0\.9([^.])@0.10$1@g' (file) changes 0.9 -> 0.10