Merge lp:~vila/bzr/rm-tweaks into lp:bzr

[Vincent Ladeuil]

Release instructions refresh.

I've refreshed the release instructions based on my past
experience as RM these last months.

I think I've read this document a bit too much to not be biased
so feel free to propose your modifications as branches so I can
easily merge them.

[Martin Pool (mbp)]

[aside] perhaps it's out of scope for this document but I wonder if we should split the more checklist like parts from the discussion.

It's spelled 'targeted' not 'targetted' despite what you may expect; also not 'targetting'.

> As of July 2010, we mantain four series (and one that is about to be EOLed).

If you're updating this I guess you mean 2011?

> relesase

typo

> 145 +#. the death of a series should be planned ahead of time

We discussed this and I believe we settled on normally stopping them after 18 months, though (as this para says) still leaving open the option to do an update if some later critical bug gets fixed. That gives up to four in flight which is enough.

> mentionning

mentioning

> practive

practice

> asssociated

associated

> chaning

changing

> A word of caution: the instructions above works well for all releases but
there is one special case that requires a bit more care: when you release
the *last* beta for a given ``x.y`` series (from trunk aka lp:bzr), you need
to setup *two* branches for the next cycle:

Since this was the main confusion this time I think perhaps it deserves a section of its own and a more explicit list of steps:

 * increment the version on trunk
 * tag the version just before you bumped the version
 * make a pqm branch from there
 * release that tagged version
 * announce that trunk is now going into the next series
(maybe more details)

I think this avoids people ever getting changes landed to the wrong place.

(perhaps some refinement of this)

> As of July 2011, bzr has applied to the technical board to be added to the `MicroReleaseExceptions
<https://wiki.ubuntu.com/StableReleaseUpdates/MicroReleaseExceptions>`__ category so that whole bugfix releases can more easily be approved.

Well, as of now we have a SRU MRE. The most useful thing here is to mention http://wiki.bazaar.canonical.com/UbuntuStableReleaseUpdates

  * ``natty`` for the 2.3 series,

You might as well also mention oneiric.

You can either treat these as tweaks or ask for a rereview.

review: Needs Fixing

[Martin Pool (mbp)]

Also, thanks for improving this.

[Vincent Ladeuil (vila)]

Inserting a comment to get separate inline diffs ;)

[Vincent Ladeuil (vila)]

> [aside] perhaps it's out of scope for this document but I wonder if we should
> split the more checklist like parts from the discussion.

I thought about it too and that's my ultimate goal: a proper
checklist with references to the discussion.

I wanted to cleanup the basis first. I'll look into making (and
validating) such checklists during the next releases.

>
> It's spelled 'targeted' not 'targetted' despite what you may expect; also not
> 'targetting'.

Thanks for catching this (and the others), I've fixed them and
then run a spell-checker that revealed a few others.

>
> > As of July 2010, we mantain four series (and one that is about to be EOLed).
>
> If you're updating this I guess you mean 2011?

Fixed.

> > 145 +#. the death of a series should be planned ahead of time
>

> We discussed this and I believe we settled on normally stopping
> them after 18 months, though (as this para says) still leaving
> open the option to do an update if some later critical bug gets
> fixed. That gives up to four in flight which is enough.

[discussion]
Yup, that's the idea, I'm not sure 4 will be enough to go from
one LTS to the other but the rules about doing less and less
releases for older stable releases should allow us to reach the
important goals:

- maintain LTS releases,
- don't release stuff nobody cares about

By 'we settled on' do you mean the 'whether we keep supporting
LTS directly or via the ppa' is not an open question anymore ?

> > A word of caution: the instructions above works well for all releases but
> there is one special case that requires a bit more care: when you release
> the *last* beta for a given ``x.y`` series (from trunk aka lp:bzr), you need
> to setup *two* branches for the next cycle:
>
> Since this was the main confusion this time I think perhaps it deserves a
> section of its own and a more explicit list of steps:
>
> * increment the version on trunk
> * tag the version just before you bumped the version
> * make a pqm branch from there
> * release that tagged version

Well, two of the last releases revealed issues at this precise
step, making it necessary to re-tag or or bump the version
(whatever works here depends on what has already been PQM'ed).

Given that both of them (re-tag or bump) are "heavy" it's better
to avoid them. That's what makes the "don't touch the branch, the
RM is working" window longer.

> * announce that trunk is now going into the next series
> (maybe more details)
>
> I think this avoids people ever getting changes landed to the wrong place.
>

Well, you can't forbid people inserting their news entry in the
wrong section (or even file) nor landing on the wrong branch.

We should make it easier to avoid the trap but we can't rewrite
history, if a proposal was made *before* the release, the news
entry cannot be in the right section.

The bit I missed was that *two* branches needed to be opened
concurrently and I mistakenly left trunk dandling while setting
up the 2.4 branch.

> (perhaps some refinement of this)

See inline MP diffs ;)

>
> > As of July 2011, bzr has applied to the technical board to be added to the
> `MicroReleaseExceptions
> <https://wiki.ubuntu.com/Stabl...

[Martin Pool (mbp)]

> > We discussed this and I believe we settled on normally stopping
> > them after 18 months, though (as this para says) still leaving
> > open the option to do an update if some later critical bug gets
> > fixed. That gives up to four in flight which is enough.
>
> [discussion]
> Yup, that's the idea, I'm not sure 4 will be enough to go from
> one LTS to the other but the rules about doing less and less
> releases for older stable releases should allow us to reach the
> important goals:
>
> - maintain LTS releases,
> - don't release stuff nobody cares about
>
> By 'we settled on' do you mean the 'whether we keep supporting
> LTS directly or via the ppa' is not an open question anymore ?

I think for LTSes we should
 - keep the bzr branch alive - we don't need to merge every fix there but we should merge safe serious fixes
 - make releases from that branch that are pushed into SRUs
 - also publish a PPA with builds of the current stable release of bzr (where that is possible; the python 2.6 transition is a case where it's not, so we'll stick at 2.3)

Does that answer the question?

[Martin Pool (mbp)]

+Since September 2010, bzr has receive approval by the technical

"Has received"

[Vincent Ladeuil (vila)]

> > By 'we settled on' do you mean the 'whether we keep supporting
> > LTS directly or via the ppa' is not an open question anymore ?
>
> I think for LTSes we should
> - keep the bzr branch alive - we don't need to merge every fix there but we
> should merge safe serious fixes
> - make releases from that branch that are pushed into SRUs
> - also publish a PPA with builds of the current stable release of bzr (where
> that is possible; the python 2.6 transition is a case where it's not, so we'll
> stick at 2.3)
>
> Does that answer the question?

Mostly, I agree with your rules but we didn't SRU for 2.0 and we probably won't. The actual situation is therefore that the stable PPA is still the way to go for some users. No big deal. I've tweaked the sentence to clarify.

[Vincent Ladeuil (vila)]

sent to pqm by email

=== modified file 'doc/developers/releasing.txt'
--- doc/developers/releasing.txt	2011-05-26 20:42:13 +0000
+++ doc/developers/releasing.txt	2011-08-04 11:48:39 +0000
@@ -2,79 +2,141 @@
 ################
 
 This document describes the processes for making and announcing a Bazaar
-release, and managing the release process.  This is just one phase of
-the `overall development cycle
-<http://doc.bazaar.canonical.com/developers/cycle.html>`_, (go re-read
-this document to ensure it hasn't been updated) but it's the most
-complex part.  This document gives a checklist you can follow from start
-to end in one go.
+release, and managing the release process.  This is just one phase of the
+`overall development cycle
+<http://doc.bazaar.canonical.com/developers/cycle.html>`_, (go re-read this
+document to ensure it hasn't been updated since you last read it) but it's
+the most complex part.
+
+If you're doing your first release you can follow this document and read
+each step explanation. It's also a good practice to read it for any release
+to ensure you don't miss a step and to update it as the release process
+evolves.
 
 If you're helping the Release Manager (RM) for one reason or another, you
 may notice that he didn't follow that document scrupulously. He may have
 good reasons to do that but he may also have missed some parts.
 
-Follow the document yourself and don't hesitate to create the missing
-milestones for example (we tend to forget these ones a lot).
-
 .. contents::
 
 
 Preconditions
 =============
 
+#. PQM access rights (or you won't be able to land any change)
+
 #. Download the pqm plugin and install it into your ``~/.bazaar/plugins``::
 
      bzr branch lp:bzr-pqm ~/.bazaar/plugins/pqm
 
+#. Alternatively, you can download and install ``lp:hydrazine`` (the main
+   difference is that hydrazine requires the branch to land to be hosted on
+   launchpad).
+
+What do we release
+==================
+
+In this document, we're talking about source releases only, packages and
+installers are built from this but we won't talk about them here.
+
+Every release is part of a series, ``bzr-2.4.1`` is part of series ``2.4``.
+
+We do two different kind of releases: the betas releases and the stable
+releases for a given series.
+
+For a given series, releases will be done to deliver new versions of bzr to
+different kinds of users:
+
+#. beta releases: named ``x.ybn`` where ``x.y`` is the series and ``n``
+   starts at 1 and is incremented. These releases are targeted to beta
+   testers who don't want to run from source but are interested in features
+   or improvements.
+
+#. stable releases: name ``x.y.z`` where ``x.y.`` is the series and ``z``
+   starts at 1 and is incremented. These releases are targeted at people
+   that want bugfixes only and no new features.
+
+
+Differences in the release process between beta and stable release will be
+mentioned when needed.
 
 When do we relase ?
 ===================
 
-As of October 2010, we mantain four series.  Concurrently releasing them
-all at the same time makes it harder to shorten the delay between the
-source availability and the package building longer than necessary (we
-delay the official announcement until most of our users can install the new
-release).
+As of July 2011, we maintain four series (and one that is about to be EOLed).
+Concurrently releasing them all at the same time makes it harder to shorten
+the delay between the source availability and the package building longer
+than necessary (we delay the official announcement until most of our users
+can install the new release).
 
 In order to continue to do time-based releases, we need to plan the
 releases by series to minimize the collisions. In the end, it's the Release
 Manager call to decide whether he prefers to do all releases at once
 though, so the rules presented here are a conservative approach.
 
-We want to respect the following rules::
-
- #. as much as possible releases should not disturb development, and
-    ongoing development should not disturb releases,
-
- #. the most recent development series should release once a month during
-    the beta period (see `Development cycles <cycle.html>`_ for more
-    details),
-
- #. the most recent stable series should release every other month (based
-    on the amount of bug fixes, this can be shorter or longer depending on
-    the bugs importance),
-
- #. previous series should relesase on a regular basis without interfering
-    with the most recent series with a decreasing order of priority (again
-    this should be based on bugs importance and user feedback),
-
- #. the death of a series should be planned ahead of time. 6 months should
-    give enough time to our users to migrate to a more recent series. This
-    doesn't mean we will make a release at the end of the series, just that
-    before the end date we _could_ possibly put out another release if
-    there was a sufficiently important fix.  Beyond that date, we won't
-    even land changes on that branch (unless something causes a miraculous
-    resurrection.)
-
- #. there should not be more than 2 releases in the same week (but the
-    Release Manager is free to ignore this (get in touch with packagers
-    though),
-
- #. the series are aligned with Ubuntu releases for convenience since we
-    create a new series every 6 months. This means that we support the
-    stable series for 18 months. Note that we also propose the most recent
-    stable series via the ppa, so whether we keep supporting LTS directly
-    or via the ppa is still an open question.
+We want to respect the following rules:
+
+#. as much as possible releases should not disturb development, and
+   ongoing development should not disturb releases,
+
+#. the most recent development series should release once a month during
+   the beta period (see `Development cycles <cycle.html>`_ for more
+   details),
+
+#. the most recent stable series should release every other month (based
+   on the amount of bug fixes, this can be shorter or longer depending on
+   the bugs importance),
+
+#. previous series should release on a regular basis without interfering
+   with the most recent series with a decreasing order of priority (again
+   this should be based on bugs importance and user feedback),
+
+#. the death of a series should be planned ahead of time. 6 months should
+   give enough time to our users to migrate to a more recent series. This
+   doesn't mean we will make a release at the end of the series, just that
+   before the end date we *could* possibly put out another release if
+   there was a sufficiently important fix.  Beyond that date, we won't
+   even land changes on that branch (unless something causes a miraculous
+   resurrection.)
+
+#. there should not be more than 2 releases in the same week (but the
+   Release Manager is free to ignore this (get in touch with packagers
+   though),
+
+#. the series are aligned with Ubuntu releases for convenience since we
+   create a new series every 6 months. This means that we support the
+   stable series for 18 months. Note that we also propose the most recent
+   stable series via the stable PPA but that the SRU processs allow us to
+   reach a wider audience.
+
+At the start of a series cycle
+==============================
+
+To start a new series cycle:
+
+#. Create a new series ``x.y`` at <https://launchpad.net/bzr/+addseries>.
+
+#. Add milestones at <https://launchpad.net/bzr/x.y/+addmilestone> to that
+   series for the beta releases and the stable series mentioning their
+   expected dates. Only the milestone associated to the next release in
+   this series should be left active to avoid clutter when targeting bugs.
+
+#. If you made a new series, you will need to create a new pqm-controlled
+   branch for this release series. This branch will be used only from the
+   first non-beta release onwards. It needs to be created by a Canonical
+   sysadmin (ask the core devs for instructions or to do it for you).
+
+#. Start a new release-notes file::
+
+       cd doc/en/release-notes
+       cp series-template.txt bzr-x.y.txt  # e.g. bzr-2.3.txt
+       bzr add bzr-x.y.txt
+
+#. Start a new whats-new file::
+
+       cd doc/en/whats-new
+       cp template.txt bzr-x.y.txt  # e.g. bzr-2.6.txt
+       bzr add bzr-x.y.txt
 
 
 At the start of a release cycle
@@ -82,45 +144,32 @@
 
 To start a new release cycle:
 
-#. If this is the first release for a given *x.y* then create a new
-   series at <https://launchpad.net/bzr/+addseries>. There is one series
-   for every *x.y* release.
-
-#. If you made a new series, create a new pqm-controlled branch for this
-   release series, by asking a Canonical sysadmin.  This branch means that
-   from the first release beta or candidate onwards, general development
-   continues on the trunk, and only specifically-targeted fixes go into
-   the release branch.
-
-#. If you made a new series, add milestones at
-   <https://launchpad.net/bzr/x.y/+addmilestone> to that series for
-   the beta release, release candidate and the final release, and their
-   expected dates.
-
-#. Create a new milestone <https://launchpad.net/bzr/x.y/+addmilestone>
-   and add information about this release.  We will not use it yet, but it
-   will be available for targeting or nominating bugs.
-
 #. Send mail to the list with the key dates, who will be the release
    manager, and the main themes or targeted bugs.  Ask people to nominate
    objectives, or point out any high-risk things that are best done early,
    or that interact with other changes. This is called the metronome mail
    and is described in `Development cycles <cycle.html>`_.
 
-#. Make a local branch for preparing this release.  (Only for the first
-   release in a series, otherwise you should already have a branch.) ::
-
-     bzr branch trunk prepare-1.14
+#. Make a local branch to prepare the release::
+
+        bzr branch lp:bzr/x.y x.y-dev
+
+   If you're doing your first beta release, branch from trunk::
+
+       bzr branch lp:bzr x.y-dev
+
+   Note that you will generally reuse the same branch for all releases in a
+   given series.
 
 #. Configure pqm-submit for this branch, with a section like this (where
-   x.y is the version to release). **Or use hydrazine for easy use**
-   ``~/.bazaar/locations.conf``::
+   ``x.y`` is the series for your release). **Or use hydrazine for easier
+   setup** ``~/.bazaar/locations.conf``::
 
-	[/home/mbp/bzr/prepare-x.y]
+	[/home/mbp/bzr/x.y-dev]
 	pqm_email = Canonical PQM <[e-mail]>
 	submit_branch = http://bazaar.launchpad.net/~bzr-pqm/bzr/x.y
 	parent_branch = http://bazaar.launchpad.net/~bzr-pqm/bzr/x.y
-	public_branch = http://bazaar.example.com/prepare-x.y
+	public_branch = http://bazaar.example.com/x.y-dev
 	submit_to = [e-mail]
 	smtp_server = mail.example.com:25
 
@@ -132,18 +181,17 @@
    
        version_info = (x, y, z, 'dev', 0)
    
-#. If you made a new series, then start a new release-notes file::
-
-       cd doc/en/release-notes
-       cp series-template.txt bzr-x.y.txt  # e.g. bzr-2.3.txt
-       bzr add bzr-x.y.txt
-
 #. Add a new section at the top of the current release notes (in
    ``doc/en/release-notes``) about the new release, including its version
    number and the headings from ``release-template.txt``.
 
 #. Update the "What's New" documents in ``doc/en/whats-new``.
 
+#. Make sure a milestone exists for your release and that it is active,
+   <https://launchpad.net/bzr/x.y> lists the existing milestones,
+   <https://launchpad.net/bzr/x.y/x.y.z/+edit> allows you to toggle the
+   active flag.
+
 #. Commit this and send it to PQM.
 
 
@@ -161,7 +209,7 @@
 #. In the release branch, update  ``version_info`` in ``./bzrlib/__init__.py``.
    Make sure the corresponding milestone exists.
    Double check that ./bzr ``_script_version`` matches ``version_info``. Check
-   the output of ``bzr --version``.
+   the output of ``./bzr --version``.
 
    For beta releases use::
 
@@ -171,10 +219,6 @@
 
        version_info = (2, 1, 0, 'beta', 1)
 
-   For release candidates use::
-
-       version_info = (2, 0, 1, 'candidate', SERIAL)
-
    For stable releases use::
 
        version_info = (2, 1, 2, 'final', 0)
@@ -187,7 +231,7 @@
 
    See *2.1.1* or similar for an example of what this looks like.
 
-#. Add a summary of the release into the "What's New" document.
+#. Add or check the summary of the release into the "What's New" document.
 
 #. To check that all bugs mentioned in the release notes are actually
    marked as closed in Launchpad, you can run
@@ -195,10 +239,12 @@
 
      ./tools/check-newsbugs.py doc/en/release-notes/bzr-x.y.txt
 
-   As of 2011-05-26, only a few false positives remain in the older
-   series. Don't let this slow you down too much. This script accepts
-   options you may find useful, use ``./tools/check-newsbugs.py`` to display
-   its usage.
+   As of 2011-07-18, all bugs mentioned in the output of the script requires
+   some sort of intervention (either changing the status if it's not 'Fix
+   Released' or setting a different milestone if the bug hasn't been
+   fixed). A few false positives may remain in the older series, don't let
+   this slow you down too much. This script accepts options you may find
+   useful, use ``./tools/check-newsbugs.py`` to display its usage.
 
 #. Commit these changes to the release branch, using a command like::
 
@@ -276,10 +322,10 @@
 
      bzr tag bzr-2.3.1
 
-#. Push those changes to a bzr repository that is public and accessible on
-   the Internet. PQM will pull from this repository when it attempts to merge
-   your changes. Then submit those changes to PQM for merge into the
-   appropriate release branch::
+#. Push those changes to a bzr branch that is public and accessible on the
+   Internet. PQM will pull from this branch when it attempts to merge your
+   changes. Then submit those changes to PQM for merge into the appropriate
+   release branch::
 
      bzr push
      bzr pqm-submit -m "(vila) Release 2.3.1 (Vincent Ladeuil)"
@@ -320,7 +366,7 @@
 Publishing the source tarball
 -----------------------------
 
-#. Go to the relevant series page in Launchpad.
+#. Go to the relevant <https://launchpad.net/bzr/x.y> series page in Launchpad.
 
 #. Create a release of the milestone, and upload the source tarball and
    the GPG signature.  Or, if you prefer, use the
@@ -331,6 +377,56 @@
    <https://bugs.launchpad.net/launchpad/+bug/586445>
 
 
+Kick off the next cycle
+-----------------------
+
+From that point, there is no possible return, the tarball has been uploaded
+so you can relax a bit.
+
+You're still holding a "social" lock on the launchpad branch though. Until
+your start the next cycle, nobody should land anything on this branch. If
+they do, they either targeted the wrong branch or didn't update the news
+file correctly, so the sooner the branch is opened again, the better.
+
+This matters more for ``lp:bzr`` than for ``lp:bzr/x.y``, ``lp:bzr`` should
+always be open for landing, so you should do `At the start of a release
+cycle`_ as soon as possible (i.e. update the version number in ``bzr`` and
+``bzrlib/__init__``, create/update the news files and create/update the
+milestone for the next relase).
+
+You may also need to do `At the start of a series cycle`_ if you're starting
+a new series.
+
+A word of caution: the instructions above works well for all releases but
+there is one special case that requires a bit more care: when you release
+the *last* beta for a given ``x.y`` series (from trunk aka lp:bzr), you need
+to setup *two* branches for the next cycle:
+
+#. ``lp:bzr`` needs to be opened for the next *series* ``x.(y+1)``
+
+#. ``lp:bzr/x.y`` needs to be opened for the next *release* ``x.y.0`` in the
+   series. Since this is first real use of ``lp:bzr/x.y``, this is also the
+   deadline for the PQM branch to be created.
+
+Both are important as ``lp:bzr`` should remain open so any change can be
+landed, ``lp:bzr/x.y`` on the other hand should be ready to receive bug
+fixes.
+
+``lp:bzr`` is generally more important as the bug fixes on ``lp:bzr/x.y``
+won't be released sooner than a month from now whereas people may already
+been waiting to land on ``lp:bzr``.
+
+In a nutshell:
+
+#. Create or update the ``x.y`` PQM branch based on whatever
+   revision you want to release
+
+#. Open ``lp:bzr`` for ``x.(y+1)``
+
+#. Release ``x.y.0`` from ``lp:bzr/x.y``
+
+#. Open ``lp:bzr/x.y`` for bug fixes
+
 Announcing the source freeze
 ----------------------------
 
@@ -341,13 +437,6 @@
    for platform maintainers and plugin authors to update their code.  This
    is done before the general public announcement of the release.
 
-
-Kick off the next cycle
------------------------
-
-#. To let developers work on the next release, do
-   `At the start of a release cycle` now.
-
 #. Pause for a few days.
 
 
@@ -378,13 +467,14 @@
 
 #. Make an announcement mail.
 
-   For release candidates or beta releases, this is sent to the ``bazaar``
-   list only to inform plugin authors and package or installer managers.
+   For beta releases, this is sent to the ``[e-mail]``
+   list only to inform plugin authors and people responsible for building
+   packages or installers.
 
    Once the installers are available, the mail can be sent to the
    ``bazaar-announce`` list too.
 
-   For final releases, it should also be cc'd to ``[e-mail]``,
+   For stable releases, it should also be cc'd to ``[e-mail]``,
    ``[e-mail]``, ``[e-mail]``.
 
    In all cases, it is good to set ``Reply-To: [e-mail]``,
@@ -413,17 +503,13 @@
 
 #. Make an announcement through <https://launchpad.net/bzr/+announce>
 
-#. Update the IRC channel topic. Use the ``/topic`` command to do this,
-   ensuring the new topic text keeps the project name, web site link, etc.
-
 #. Announce on http://freshmeat.net/projects/bzr/
 
-   This should be done for beta releases, release candidates and final
-   releases. If you do not have a Freshmeat account yet, ask one of the
-   existing admins.
+   This should be done for beta releases and stable releases. If you do not
+   have a Freshmeat account yet, ask one of the existing admins.
 
    The purpose here is to point users to the latest stable release while still
-   publishing announcements for development releases.
+   publishing announcements for beta releases.
 
    There are several kinds of modifications that could be done there via the
    ``Administration`` box in the lower right area of the page:
@@ -432,32 +518,31 @@
      ``Links`` box are edited. This should rarely change except for the URLs
      related to the latest stable release.
 
-   * New announcement: When doing a release (beta, candidates, final), put the
-     summary of the release (you can't embed URLs there, the moderation staff
-     remove them). Users can still access the releases notes via the ``Release
-     Notes`` URL in the ``Links`` box in the upper right area of the
-     page. When doing the first stable release in a series, delete the
-     ``Unstable installers`` <https://launchpad.net/bzr/x.y/x.ybn> and
-     ``Unstable source tarball``
+   * New announcement: When doing a release, put the summary of the release
+     (you can't embed URLs there, the moderation staff remove them). Users
+     can still access the releases notes via the ``Release Notes`` URL in
+     the ``Links`` box in the upper right area of the page. When doing the
+     first stable release in a series, delete the ``Unstable installers``
+     <https://launchpad.net/bzr/x.y/x.ybn> and ``Unstable source tarball``
      <http://launchpad.net/bzr/x.y/x.ybn/+download/bzr-x.ybn.tar.gz>
-     links. Conversely, when creating the first beta in a development series,
-     create these links again. Check all links when doing other kinds of
-     release.
+     links. Conversely, when creating the first beta in a development
+     series, create these links again. Check all links when doing other
+     kinds of release.
 
    * Set direct download: When releasing a new stable release, this should
      point to the corresponding launchpad page:
      <https://launchpad.net/bzr/x.y/x.y.z/>
 
 #. Update `<http://en.wikipedia.org/wiki/Bazaar_(software)>`_ -- this should
-   be done for final releases but not for beta releases or Release Candidates.
+   be done for the stable and beta releases.
 
 #. Update the python package index: <http://pypi.python.org/pypi/bzr> - best
    done by running ::
 
        python setup.py register
 
-   Remember to check the results afterwards -- this should be done for
-   final releases but not for beta releases or Release Candidates.
+   Remember to check the results afterward -- this should be done for
+   stable releases but not for beta releases.
 
    To be able to register the release you must create an account on
    <http://pypi.python.org/pypi> and have one of the existing owners of
@@ -467,10 +552,9 @@
 Merging the released code back to trunk
 ---------------------------------------
 
-Merge the release branch back into the trunk.  The
-``doc/en/release-notes`` changes should be merged into the right place
-because each release series has its own release-notes file, but
-double-check.
+Merge the release branch back into the trunk.  The ``doc/en/release-notes``
+changes should be merged into the right place because each release series
+has its own release-notes file, but double-check.
 
 If it's not already done, advance the version number in ``bzr`` and
 ``bzrlib/__init__.py``.  Submit this back into pqm for bzr.dev.
@@ -479,24 +563,21 @@
 created the corresponding milestone to ensure the continuity in bug
 targeting or nominating. Depending on the change, you may even have to
 create a new series (if your change the major or minor release number), in
-that case go to `At the start of a release cycle` and follow the instructions from there.
+that case go to `At the start of a series cycle`_ and follow the
+instructions from there.
 
-You should also merge (not pull) the release branch into
-``lp:~bzr/bzr/current``, so that branch contains the current released code
-at any time.
 
 Releases until the final one
 ----------------------------
 
-Congratulations - you have made your first release.  Have a beer
-or fruit juice - it's on the house! If it was a beta, or
-candidate, you're not finished yet. Another beta or candidate or
-hopefully a final release is still to come.
+Congratulations - you have made your first release.  Have a beer or fruit
+juice - it's on the house! If it was a beta, you're not finished
+yet. Another beta or hopefully a stable release is still to come.
 
-The process is the same as for the first release. Goto `Doing a
-particular release`_ and follow the instructions again. Some details change
-between beta, candidate and final releases, but they should be
-documented. If the instructions aren't clear enough, please fix them.
+The process is the same as for the first release. Goto `Doing a particular
+release`_ and follow the instructions again. Some details change between
+beta and stable releases, but they should be documented. If the instructions
+aren't clear enough, please fix them.
 
 
 Getting the release into Ubuntu
@@ -515,10 +596,15 @@
 the `SRU (Stable Release Updates)
 <https://wiki.ubuntu.com/StableReleaseUpdates>`__ process.   
 
-As of September 2010, bzr has applied to the technical board to be added
-to the `MicroReleaseExceptions
+Since September 2010, bzr has received approval by the technical
+board for the `MicroReleaseExceptions
 <https://wiki.ubuntu.com/StableReleaseUpdates/MicroReleaseExceptions>`__
-category so that whole bugfix releases can more easily be approved.
+category so that whole bugfix releases can more easily be
+approved.
+
+Progress on these realeases is tracked on the `SRU wiki
+<http://wiki.bazaar.canonical.com/UbuntuStableReleaseUpdates>`_
+page.
 
 **After making a bzr stable-release release, nominate the most serious bug
 for the appropriate Ubuntu release and subscribe the `ubuntu-sru` team.**
@@ -535,9 +621,10 @@
    button and select the right Ubuntu release. As of September 2010, this
    means:
 
+  * ``oneiric`` for the 2.4 series,
+  * ``natty`` for the 2.3 series,
   * ``maverick`` for the 2.2 series,
   * ``lucid`` for the 2.1 series,
-  * ``karmic`` for the 2.0 series.
 
  * Subscribe the ``~ubuntu-sru`` team to the bug.
 

=== modified file 'doc/en/release-notes/bzr-2.5.txt'
--- doc/en/release-notes/bzr-2.5.txt	2011-08-03 14:35:06 +0000
+++ doc/en/release-notes/bzr-2.5.txt	2011-08-04 11:48:39 +0000
@@ -85,6 +85,8 @@
 
 .. Improved or updated documentation.
 
+* Release instructions refreshed. (Vincent Ladeuil)
+
 API Changes
 ***********
 

=== added file 'doc/en/whats-new/template.txt'
--- doc/en/whats-new/template.txt	1970-01-01 00:00:00 +0000
+++ doc/en/whats-new/template.txt	2011-08-04 11:48:39 +0000
@@ -0,0 +1,26 @@
+*************************
+What's New in Bazaar x.y?
+*************************
+
+Bazaar x.y is still under development, and will be released in Month Year.
+This document accumulates a high level summary of what's changed.  See the
+:doc:`../release-notes/index` for a full list.
+
+<topics of interest here>
+
+Further information
+*******************
+
+For more detailed information on the changes made, see the the
+:doc:`../release-notes/index` for:
+
+* the interim bzr `milestones <https://launchpad.net/bzr/x.y>`_
+* the plugins you use.
+
+For a summary of changes made in earlier releases, see:
+
+* :doc:`whats-new-in-2.1`
+* :doc:`whats-new-in-2.2`
+* :doc:`whats-new-in-2.3`
+<intermediate series here>
+* :doc:`whats-new-in-x.(y-1)`