Mark,

[long one coming up....]

On Thu, 29 Apr 2004, Mark Taylor wrote:

> I've taken a look at this now, and have some comments.

I'm relieved.  I was starting to worry that noone had noticed or, worse,
was planning to simply agree.

> Although it
> is nice to have procedures codified (especially things like what
> tag/branch names to use), some of the ones that you've written
> here are pretty heavyweight.

I would probably prefer `described in longwided detail' for the
single-components section at least.  Having actually done this once or
twice with the various autotools branches, I can confirm that the 6+5
steps described in the single-component section actually _feel_ like
only one or two steps in practice.  That is, I find this is actually a
lot more lightweight than I've made it sound.

The reason for the detail was that when I tried actually applying my own
suggestions in the previous version of this page, I found they were
ambiguous and incomplete.

Overall, tag and branch conventions are not really separable from
the `policies' or practices they're linked to -- it's not feasible
to separate the two things.  It's only because the tag conventions
correspond closely with specific practices (and there are only a few
of each), that you don't need a spelled-out `codeline policy' for each
branch, held in some conventional file.  If I see a branch called
`RELEASE-xxx', then I know what it's for and what will happen to it,
without any further bureaucracy.

It will help, therefore, to have as few policies and variants as possible.
Thus since we will _sometimes_ want to have a release branch for a
component, I suggested we should _always_ have a release branch --
no variants.  That means that if you want to look at version x.y of some
component `cpt' (I come back to this below), you know that there _will_
be a branch RELEASE-cpt-x-y and don't have to look through the list of
tags on a component to find out what's there; so you can check out the
HEAD of that branch without further thought or investigation.  That is,
the motivation was to make this process more lightweight, not less.

I don't think this is a big deal, though.  If you need to make some
bugfixes to a particular release, and there isn't a branch there
already, then you add a bp-<releasetag> tag to the repository and make
the branch at that point.  It would be feasible to not bother with the
bp- tag and just mandate that if the bp-<releasetag> tag isn't present,
then the branch must have been made from the point tagged <releasetag>.
It is starting to get a bit more complicated to explain, though, and
requires a little bit of deduction with the tags on a component to work
out what its history has been and what you're supposed to do next.

This does presume that the term `release' is applied to something more
fine-grained than the bi-annual USSC (as you observed).  On the page I
distinguish major and minor releases, which do have functionality changes,
and where the minor version number changes, from patch releases, where
there's in principle no functionality change, just a bugfix, and only
the patch number changes: m.n-r -> m.n-(r+1).  I think this is fairly
conventional terminology and practice, and it's what I at least have
tended to do, more consistently recently than before.

Why is that distinction important?  Because I strongly believe the USSC
distribution should be based on a collection of component tags (that is,
version x.y-z of that component, version u.v-w of the other) and NOT
based on simply snapshotting the entire tree.  Because development is
happening on the tree most of the time (this will become less true of
much of the classic tree, but more true of the Java parts), you can't
reliably say that the HEAD of any particular component's trunk is the
version that should go in the USSC release.

That is, the USSC release is formed, not necessarily from the bleeding
edge versions of components, but instead from a list of versions that
can be verified -- tested -- to work together.

That has two corrolaries.  First, that unit testing and integration
testing become orthogonal.  Unit testing is the assertion that `this
component discharges its interface contract correctly', in isolation
from other components; integration testing is more project-wide, and is
the assertion that `this group of components are able to work together
successfully', and is more of an assertion about interfaces than about
implementations.  The first is something that JUnit, say, can help with
fairly mechanically; the second might involve more by-hand testing, or
beta-testing, or other elaborate review that might be worth doing properly
only biannually, over some longish period (one or two months?) prior to
a USSC release.  Some longish period, crucially, in which the code base
might reasonably be expected to evolve.

Secondly, it makes it more likely that we'd have to go back to a
non-current release and fix a bug that the integration had exposed,
without changing an interface, and therefore without simply replacing
the component with the latest-and-greatest one, since this may have a
different interface or feature-set, so that the replacement might cause
other components to stop working.

Alternatively, if a bad bug appears in a distributed USSC release,
which we want to fix, then we need to drop in a patched release of the
same minor version, so we don't risk breaking the distribution as a whole.

>    I'm not very keen on the rule "All releases must be made off a
>    release branch".  My current model for TOPCAT releases (not including
>    the USSC release) is, when I've made some functionality improvement
>    which I don't believe will break anything else, or fixed a bug
>    I think has a reasonable chance of being encountered by users,
>    I rebuild, run the unit tests, and put the new copy on the web page.

Fine -- a new minor version.  Or a new patch release.

I proposed that patch releases should go on a branch for the sake of
consistency (which I'm a sucker for), but there's no real reason why
they can't go on the trunk, and create branches only when it turns out
to be necessary, either because Steve has to make pre-release tweaks
to documentation, say, or because you've had to go back to an earlier
release for the reasons mentioned above.  Slightly less consistency
means you might have to do a little more thinking about the state of the
component, but that's probably a good tradeoff for the extra convenience
of not having multiple branches.  With fewer variants of procedures,
there's less state to infer from the tags on a component.

>    Probably, I ought to be tagging it
>    as well

Since this is zero effort, yes, I think so.

>            (the tag would have to be on much or all of the starjava
>    set, not just the topcat/ dir).

Eeek, are you serious?  That means that tags get plastered all over the
(starjava part of the) repository, even on largely unrelated components.
The most trivial of the practical problems with that is that you'd end
up with pages of tags listed in the `cvs status -v' output, giving you a
hard time working out which tags are relevant, and which tags are there
simply to assert that this package (ant?) didn't break Topcat.

In other words, what you're doing with this broad-brush tagging is
simultaneously unit testing (`Topcat has reached a temporarily releasable
stage') and integration testing (`Topcat works with the other packages
in the repository').

And it's not just Topcat: if Alasdair wanted to tag some random release
of Frog, he'd also tag the entire repository; so would Peter with Splat.
And so on.  There'd be so many tags on barely-releated packages that
it would make the tag list unmanageable, because most of the tags on a
package would carry almost no information.

It's presumably fairly obvious that I do not think that the entire
starjava tree should be regarded as a single giant component.  That's
hopelessly unwieldy.  The natural components are the directories under
java/source, which have a 1-1 correspondence with uk.ac.starlink.x.*
package groups -- not individual packages, which are too closely
integrated that you'd ever want to release/update them on different
schedules.

>    Something more careful might be warranted for single-component
>    release of libraries intended for ues by third parties as
>    opposed to applications.  Again, this is not a service we
>    currently provide in any formal fashion.

The problem is that Topcat might require version x.y-z of jniast, while
Splat needs x.y-w, and their interim releases (ie, between USSCs) would
be packaged with those nominated releases of the jniast component.

The USSC would be the time when those different applications' requirements
would be reconciled, so that all the Java application components that went
into the USSC release would work with a common set of library components.

> USSC releases:
>
>    Heavyweight procedures are more defensible for a USSC release, but
>    even so, it does sound terribly complicated.  Under the proposed

Well, yes, it surprised me.

Given the principle that a USSC release consists of a list of component
versions, Steve (`release manager') has the problem of identifying which
set of components will actually work together.  I imagine that would
actually be fairly straightforward, and more-or-less consist of the
latest tagged version of each component.  The intricacies on the wiki
page are an attempt to work out the consequences of this in nitpicking
detail, to see if the principles there are actually unworkable.  I do
not claim that the procedure in that section is necessarily the best way
of implementing those ideas -- it _does_ seem too fiddly, and prodigal
with branches.

>    How about sticking with the procedure we've got this time round -
>    one release branch additional to the trunk with codeline owners
>    responsible for (a) checking in bugfixes on the release branch
>    that arise from their own or other people's testing and (b)
>    bringing the trunk up to date with the same fixes as they see fit.

That's more-or-less what I'm suggesting, except that it's pretty
effectively obscured by the forest of specifics and CVS commands
involved in working it out in detail.  Sorry 'bout that.

The only real difference from the procedure this time round is that,
rather than just snapshotting the HEAD of the entire tree, I suggest
making the branch on only a subset of components (ie, we don't include
obsolete or dropped components like adamnet in the branch), and only at
particular tags which we believe constitute a set of components which
does work successfully together.  That might mean including a version
of Topcat which is a couple of releases old, if it has pushed too far
in front of the other packages, and requires a set of library components
which break other applications.

If you already have release branches, then this step becomes easy to
document; if not, there would be extra intricacies.

Since Steve _might_ have to take a couple of shots at this (though, again,
probably not in practice), then he might need to do the make-a-branch
step more than once.  Hence the multiple branches mentioned in the wiki
page.

>    Are there reasons why the procedure from this release is deficient?

Only that it involves snapshotting the entire tree, which is probably
not what you want.

If you want to make a release by snapshotting the HEAD of the trunk,
then you're forced to require that the HEAD of the trunk be always in
a releasable state -- not just buildable, but ready for the public.
That means that _all_ developments which aren't absolutely dead-cert,
one-commit, releaseable should be done on branches, so that we end up
with more branches rather than fewer.  Either that, or you have a code
freeze, and have folk twiddling their thumbs while you wait for the HEAD
to get into a consistent state before branching it.  Tags and branches
help you avoid having to do that.

If you want a snapshot release, then we can produce it easily, every
night or every week, and if it breaks you get to keep both bits.  But I
don't think it should be the USSC release.

Users are familiar with the idea that the components in a large
distribution might not be the absolutely most recent ones, and are
happy with this in that majority of cases where they value stability
over last week's new functionality.  Debian has `stable', `testing'
and `unstable' releases.  I'm obviously not suggesting this degree of
elaboration, but it's that pattern I have in mind.

All the best,

Norman


--
---------------------------------------------------------------------------
Norman Gray                        http://www.astro.gla.ac.uk/users/norman/
Physics and Astronomy, University of Glasgow, UK     [log in to unmask]