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)

There are two relationships between branch and series. The first is the existing relationship, where a branch essentially is a series. This is stored in the ProductSeries.user_branch column. The second is that when a branch is intended for a series. We already have something of that second relationship in 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.

• Branches have a dichotomy of lifespans. Bug/feature branches are very short, as a rule, whereas trunk & release branches are very long-lived.

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

Upstream Branches

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

~bzr/bzr/mainline/bzr.dev

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

1. The branch that *is* the line of development (in some sense)
2. Branches that are *intended for* a specific landmark on a line of development (which could be the horizon).

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

(which happens to be kickass)

This NEEDS to get the latest version.

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. 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

He hacks the branch to get the interesting bits out of it, creates the new release, and pushes:

$ bzr push lp:~wouter/bazaar/1.3.1/nested_branches

Magic.

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/

On Fri, Nov 14, 2008 at 5:30 AM, Christian Robottom Reis
<kiko@canonical.com> wrote:
> Some comments for before the call.
>

Thanks for these comments Kiko.

The document was intended to focus primarily on use-cases and is
really notes from a call rather than a spec. I'll try to hammer out
more of the use-cases and address the gaps that you mention, but only
after I've had a chat w/ thumper and got the results from your call
with Mark.

Once that's done, I'll whack this on a wiki page so we can keep editing it.

>> == Personal Branches ==
>>
>> ~jml/(ubuntu/openssh)/break-dsa
>>
>> OR
>>
>> ~jml/ubuntu/jaunty/openssh/break-dsa
>>
>> OR
>>
>> ~jml/ubuntu/jaunty-security/openssh/break-dsa
>
> This is fine, though it's missing an example of
> ~jml/openssh/series/break-dsa
>

The section should have read "Personal Source Package Branches".
You're right that we should probably consider them both together.

>> Within a line of development, there are two sorts of branches:
>>   1. The branch that *is* the line of development (in some sense)
>>   2. Branches that are *intended for* a specific landmark on a line of
>>      development (which could be the horizon).
>
> This is a great piece of insight but the conclusions that follow the
> sentences are not present. What does that mean in terms of URLs?
>

This was more of a floating piece of text hammered out during
discussion rather than part of the document proper. Definitely worth
thinking about.

>> And then Ubuntu gets released again:
>> $ bzr pull
>> bzr+ssh://bazaar.launchpad.net/ubuntu/+latest/gedit
>>
>> (which happens to be kickass)
>>
>> This NEEDS to get the latest version.
>
> What happens when this happens? Does bzr info change what it says at the
> point of the bzr pull?

No. bzr info still says "bzr+ssh://bazaar.launchpad.net/ubuntu/+latest/gedit"

> Do all revisions that are in kickass and not
> jaunty get pulled in?
>

Yes.

>> == 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
>
> Wow. Is this really what we want to be listing in the branch listing
> pages? Doesn't this lead to a crazy profusion of branches?
>

Well, I believe the idea is that the "main" listings are the (product,
productseries) listings. 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.

It will lead to a profusion of branches. I don't think that it's a
problem. Do you think it is?

>> 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.
>> 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
>>
>> He hacks the branch to get the interesting bits out of it, creates the new
>> release, and pushes:
>>
>> $ bzr push lp:~wouter/bazaar/1.3.1/nested_branches
>
> Hang on there! 1.3.1 is a release, not a series. Is this correct?
>

Good question! I'll ask Martin what he meant here.

>> Matt hits a button / runs a script that says "close off jaunty".
>
> 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.

We didn't get this one finished due to time constraints.

jml