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, ...)
- Uraeus and thomasvs get tired of the general laziness

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.

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
      cvs update -r BRANCH-RELEASE-0_3_3
  - Set the nano to 2 (in configure.ac, AS_VERSION)
  - Do all updates/patches/changes for the release tarball in this branch
  - Think of a good codename for the release
  - 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
    - grepping ChangeLog for contributors:
 grep "<.*>" ChangeLog | perl -i -p -e 's@\d*-\d*-\d*\s*(.*)\s*<.*$@$1@' | sort | uniq
  - 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)
  - 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
      - 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
  - make a text copy of the release notes to be included in the tarball :
    lynx -dump http://gstreamer.net/releases/$(module)/$(version) > NEWS
    or
    links -dump "http://gstreamer.net/releases/$(module)/$(version)" > NEWS
    (FIXME: still need to remove the menu from this manually, maybe make
    some xslt instead to do this ?)

  - 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
  - tag tree
    for example for 0.6.3 :
           cvs tag RELEASE-0_6_3
  - roll the tarball, build rpms
  - run "make upload" from gstreamer/docs to get the new docs online
  - change www/src/htdocs/entities.gst with the new version numbers
  - 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)
  - 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)
    * 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.