These are all notes. Please combine these into something coherent. -- jml

Bind branches to product series

Status: Very rough draft. Please edit.

Blueprint: branch-product-series

Outline derived from David Allen's "Natural Planning Model". Not sure how useful the last two sections will be here. -- jml

Currently, branches in upstream projects are bound primarily to that project and in general have no link to a product series. This specification discusses how Launchpad might work if all branches had an associated product series.

Actually, it's not precisely a spec. It's more of a document to focus discussion.

Purpose (Why are we even talking about this?)

• We are seriously thinking about making source package branches belong to distroseries, and we want there to be consistency between upstream and distro.
• Part of Launchpad's value comes from being a reliable reflection of activity. Binding branches to series might improve Launchpad's ability to show currently active branches.
• By binding all branches to users, we might encourage them to place a greater focus on regularly releasing software. (Not sure how this works, but it's been raised -- jml)
• It's complex, there are a lot of edge cases and it'll be a lot of work, so the discussion is worth writing down.

Principles (I'd let anyone take over this as long as they... )

• Smooth migration from current model.
• Add no overhead in starting new, small, projects.
• Make the concepts and user interface bleedingly obvious, particularly for CVS / SVN refugees.
• Keep consistency between distro and upstream.
• Break the work down into manageable chunks that each provide value to the end user.

Desired Outcome (What does wild success look like?)

Bazaar interactions

Fetch trunk:

$ bzr branch lp:python trunk

Push up a personal branch:

$ bzr push lp:~jml/python/2.6/fix-something

Fetch a branch of something:

$ bzr branch lp:~jml/python/3.0/another-patch

Brainstorm (Any ideas at all)

Within a line of development, there are two sorts of branches:

1. The branch that *is* the line of development (in some sense). This branch tends to be long-lived. This information is already stored in the database.
2. Branches that are *intended for* a specific landmark on a line of development (which could be the horizon). This branch tends to be short-lived. We kind of store this with merge proposals -- perhaps we can make a bigger deal out of that?

• Talk to MySQL about the productseries-branch thing. This affects all our users and we should get their input, but MySQL are perhaps one of the most active and major non-Canonical users.

There are three separate, interesting things being discussed here:

1. Launchpad supporting source package branches.
2. Upstream branches being tied to product series rather than products.
3. The Bazaar client storing information about what branch the user asked for and what branch they got, then presenting the user with choices when the "got branch" changes.

Organize (Turn this into a real spec)

Next Actions (File bugs)

Notes from other calls

Introduction

Terminology

Distribution: ubuntu, debian
Distribution Series: hardy, jaunty
Pocket: release, security, updates, backports
Distribution Suite: <series>-<pocket>. e.g. hardy (hardy + release pocket), 
    hardy-security, hardy-backports.

Official Packages

/ubuntu/jaunty/openssh
/ubuntu/jaunty-security/openssh
/debian/woody/nautilus
/ubuntu/+latest/openssh -- or +devel or +horizon

Personal Branches

~jml/(ubuntu/openssh)/break-dsa

OR

~jml/ubuntu/jaunty/openssh/break-dsa

OR 

~jml/ubuntu/jaunty-security/openssh/break-dsa

OR

~jml/openssh/2.2/break-dsa

Upstream Branches

~jml/bzr/1.10/bug-link-coolness

~bzr/bzr/mainline/bzr.dev

Stories

Note: "jaunty" is the current version of Ubuntu being developed (ubuntu+1). "intrepid" is the version just released. "kickass" (for "The Kickass Koala) is the version after jaunty. "kickass" is not actually the official name.

Note: stacking is well out of scope. We'll do something that makes sense.

John, the lazy Ubuntu developer

John is an Ubuntu developer who works on the OpenSSH package. He's made some fixes to the packaging, and he want to push them to Launchpad. He would:

$ bzr push lp:~john/ubuntu/openssh/john-fixes

The Canonical URL for this would be: /~john/ubuntu/jaunty/openssh/john-fixes

6 months later, John has been lazy and never got his branch merged in. He then does some additional changes, and pushes again:

$ bzr push lp:~john/ubuntu/openssh/john-fixes

The Canonical URL for this would be: /~john/ubuntu/kickass/openssh/john-fixes.

The branch is accessible through:

lp:~john/ubuntu/kickass/openssh/john-fixes
lp:~john/ubuntu/openssh/john-fixes (alias for ubuntu/kickass/openssh/john-fixes)

The branch, as of the last push to jaunty is at:

lp:~john/ubuntu/jaunty/openssh/john-fixes

Kevin the busy Ubuntu Hacker

Kev starts working on gedit:

$ bzr branch lp:ubuntu/gedit trunk

(this gets the latest, which happens to be jaunty)

lp:ubuntu/gedit --> bzr+ssh://bazaar.launchpad.net/ubuntu/+latest/gedit

Kev makes a whole bunch of branches all the time:

$ cd gedit
$ bzr branch trunk foo-stuff
$ bzr branch trunk obby-support

And sometimes he pushes these branches up to Launchpad:

$ bzr push lp:~kev/ubuntu/gedit/obby-support

He gets fresh updates to trunk by pulling:

$ bzr pull

Pulling from lp:ubuntu/gedit

And then Ubuntu gets released again:

$ bzr pull
bzr+ssh://bazaar.launchpad.net/ubuntu/+latest/gedit
$ bzr info -v
Parent branch: bzr+ssh://bazaar.launchpad.net/ubuntu/+latest/gedit

...which happens to be kickass. All the revisions that are in kickass and not in jaunty will be pulled in. If jaunty and kickass have diverged, then Bazaar will raise its "diverged branches" error.

Doris the Bazaar Hacker

Doris fixes a bug in Bazaar, and pushes her change to Launchpad:

   bzr push lp:~doris/bzr/super_fix

The branch is now accessible through:

lp:~doris/bzr/super_fix
lp:~doris/bzr/1.10/super_fix

Wouter the Bazaar developer

Wouter has been working on the Nested branches feature since bzr 1.2. He pushes every sporadically, but never really merges into trunk because he's afraid of reviews. Wouter has always pushed and pulled from:

lp:~wouter/bazaar/nested_branches

BUT, the following canonical URLs have been created:

~wouter/bazaar/1.2/nested_branches
~wouter/bazaar/1.3/nested_branches
~wouter/bazaar/1.5/nested_branches
~wouter/bazaar/1.6/nested_branches
~wouter/bazaar/1.9/nested_branches

Bzr's version in Hardy is 1.3, and Wouter realizes that it has a critical bug which he had a fix at the time, so he wants to create a 1.3.1 release.

This leads to a profusion of branches, but if well-managed this is not a problem. First, the primary listings will be on (product, productseries), so at most one version of "nested branches" will appear. After all, the big idea with linking to productseries is to hide branches that are not a part of the current, interesting lines of development.

Ideally, there would be a page, say ~wouter/bazaar/nested_branches or ~wouter/bazaar/+all/nested_branches that linked to all the series branches where nested-branches occurred. (XXX - haven't thought about how to implement this, seems non-obvious - jml).

He now goes to Launchpad and finds his branch at the 1.3 release, and does:

$ bzr branch lp:~wouter/bazaar/1.3/nested_branches

What actually happens when Ubuntu is released

Matt the Canonical Ubuntu employee has just released Ubuntu Jaunty. He's tired, slightly hungover and he has to open up development Kickass. Ubuntu has about 20G worth of branches.

Matt hits a button / runs a script that says "close off jaunty".

From now on, all new pushes create a new canonical name/branch with /kickass/

"+latest" now binds to /kickass/

• > How much work is this? Is it just changing a single attribute on the
  > distribution? Right now the process for opening/closing a release is
  > pretty involved, which is why I'm asking about this ahead of time.

Opening a series

Distro

• pretty much want to have the official branches of the new series available
  • from the get-go.
• opening jaunty != closing intrepid;
  • jaunty is opened for development before intrepid is closed. e.g. intrepid-updates

So when does /ubuntu/openssh refer to jaunty rather than intrepid, I hear you ask.

Upstream

• "Doing a release"

• "Opening development for a release" <-- does this ever make sense? who does

  • this? only crazy people. and Python.

Doing an upstream release, when it's serious business

Bazaar releases every[1] month. What happens is that the Release Manager (RM) at some point makes a branch of trunk (aka bzr.dev) that the release will ultimately be made from. A tarball is made from this branch and advertised as the release candidate. Meanwhile, Bazaar developers keep making branches from trunk. These branches are considered to be part of the next release.

If a problem is found in the release candidate, the fixing developer branches the release branch, makes his fix and merges it into the release branch.

Ultimately the release is made from the release branch. If a point release is required, further changes will be committed to the release branch and another release made from the branch.

IN THE NEW WORLD (MAYBE):

We donn't have a branch called "bzr.dev". There would just be the series branch for the 1.8 series.

• Series 1.8 *
  • A BRANCH (accessible as lp:bzr and as lp:bzr/1.8)

(the "*" means that this is the development focus series)

Then, when the release candidate is being made, the RM hits a button that "clones" this line of development (and the associated Bazaar branch), with the option to make the new series the development focus.

• Series 1.9 *
  • THE OLD BRANCH (accessible as lp:bzr and lp:bzr/1.9)
  Series 1.8
  • A NEW BRANCH (accessible as lp:bzr/1.8 and probably stacked on lp:bzr)

(though it doesn't really make sense to think in terms of new and old branch here, they'd both have the same tip revision immediately after the operation).

OPEN QUESTION: Canonical names for "official" upstream branches. MAYBE ANSWER: maybe the canonical url is "code.launchpad.net/$project/$series"

"AIEEEEE" THOUGHT: Project groups?

lp:~wouter/bzr/1.8/nested_trees after release what does pulling lp:~wouter/bzr/nested_trees mean? (particularly when you pull from it, push is moderately clear) maybe just 404ing until a new branch is created is ok.

• Option 1: 404 Option 2: If the 1.9 branch doesn't exist, then resolve to the "latest" non-
  • release branch.
  Option 3: Bazaar tells LP the last name it got when it did a lookup...

OBSERVATION: the "development focus" property is actually sticky on a branch. That is, ~bzr/bzr/bzr.dev is *always* the development focus. Given that our data model goes product -> anointed series -> anointed branch, this is a bit crap.

Releasing Ubuntu

Ubuntu releases every six months. When it releases, we do what we do above, except once per source package.

Obsolete? text

Question: outline the changing relationships between branch and series during a release.

We are making the 1.8 release. It starts off like this:

• Branch ~bzr/bzr/bzr.dev
  • Series: 1.8 *

We make a new branch:

• Branch ~bzr/bzr/1.8

Then we do a dance:

Make a new series:

• Series 1.9

And rejigger the series such that:

• Branch "~bzr/bzr/bzr.dev" (but actually, lp:bzr, lp:bzr/1.9 -- what's canonical?)
  • Series: 1.9 *
  Branch "~bzr/bzr/1.8"
  • Series: 1.8

That is:

• - series 1.9 is the development focus series - series 1.8 is associated with the 1.8 branch