Re: Bug tracker and transplants

[John W. Eaton]

On  4-Apr-2011, Rik wrote:

| I'm not sure about how much work there is, but I think this is an excellent
| time to experiment and make a small point release (3.4.1).  First, we've
| fixed a number of errors that were bound to happen with any *.*.0 release.

I don't think there have been many major changes except for some
things in graphics.cc.  I haven't checked to see whether the changes
there would cause binary incompatibility going from 3.4.0 to 3.4.1.
If so, then maybe they would need to be omitted since one of the goals
is to preserve binary compatibility for all point releases in a given
series, so for example, .oct files built for any 3.4.x version should
work with any other 3.4.x version.

I did try a merge of release-3-4-x to default and found 179
conflicts.  Of those, 90 are in NEWS, mk-opts.pl, README.MacOS,
and ChangeLog files.  Another 46 are in graphics.cc or graphics.h.in.

But none of that matters if we can determine that there are no binary
compatibility problems going from 3.4.0 to the current development
version and we decide to just use the current development version as
the starting point for 3.4.1.  In that case, merging is just a
formality since we would really just merge to clean up the revision
history and the end result would just be the default branch.  Then we
would create a "stable" branch and start working with the new rules
for commits.

| And for those who would rather not understand all the gritty details of the
| version control system, are there some simple rules that could be published
| and also added to the Contribution Guidelines section of the
| documentation?

Yes, I think it would be fairly simple.  Primarily, bug fixes that do
not introduce binary incompatibility in the current release series and
improvements in documentation for the current release should be
applied to the stable branch.  All other changes (code refactoring,
new functions, new features, or documentation for them) would go on
the default branch. The stable branch would periodically be merged
with the default branch.

The thing that I think could cause confusion is that now people with
commit access need to be more aware of which branch they are working
on and may need to switch between them depending on whether they are
fixing a bug or working on a new feature.  For a large project like
Octave that takes a nontrivial amount of time to compile, probably the
best thing to do would be to maintain two separate copies of the
sources to avoid needless recompilation when switching branches.

| I read the discussion, but it still wasn't immediately obvious to me how
| I, as a developer, should behave and what the benefit was.

The benefit is mostly to the release manager, I think, by not having
to decide what patches to transplant.  Instead, that decision would
normally be made in advance of making the change instead of after.  So
instead of making a change on the default branch as we do now, then
having to go back and review the changes and decide what should be
applied to the current release series, we instead make bug fixes on
the stable series first, then those are applied to the default branch
when we merge stable with default.

Normally, I would expect a smaller number of changes on stable than we
have going in to default, but maybe that is too optimistic.  Many of
the changes since 3.4.0 have been bug fixes, but we also have a few new
functions and features.  The new things could be left out of 3.4.1,
and if we switch to the stable+default workflow, changes like that
should probably not be applied to stable in the future, but I don't
see a big downside for including them in 3.4.1 if there aren't binary
compatibility problems and it simplifies switching to the new
workflow.

| the frequent merges of stable to default (recommended every 8-10
| changesets) are being done by the release manager (jwe) or by individual
| coders?

Normally I guess it would be up to the release manager(s) to do the
merges.

| For example, while fixing a bug I often find a little something
| else that could be done in the nearby code.  I can break the changeset into
| one which is a pure bug fix and applied to stable, but then I would
| presumably need to immediately merge that change down to default, and
| finally add the new code.

If the changes don't overlap, then you could apply the bug fix to
stable and the other change to default and then wait to merge.  You
could even do this if a conflict would result, but then it might be
helpful if you did the merge since properly resolving a merge often
requires knowledge of what the intent of the changes are.

| Also, would it be worthwhile to incorporate more naming standards for the
| Mercurial ChangeLog entries?  We currently have '(bug #NNNNN)' which should
| allow the release manager to quickly find bugs.  Do we want a facility for
| marking documentation changes so that they could be found easily as well?
| Perhaps it doesn't matter if doc fixes are always applied to stable.

I don't think it is needed if we are in the habit of thinking that
changes that should go in the next point release are made on stable.
But that doesn't mean that just because a bug is being fixed that the
change belongs on stable.  It still depends on what kind of bug it is
and whether the change would be risky.  So to ensure that each point
release has a good chance of being better than the last, we need to be
fairly conservative about what is applied to the stable branch.

I did a small amount of testing to see what would happen with two
cases I was concerned about:

  create a stable branch
  remove FILE from default
  make a change to FILE on stable
  merge stable with default

At this point, Mercurial prompted me with

  remote changed FILE which local deleted
  use (c)hanged version or leave (d)eleted? d

This is a case in which it is important to know the intent of the
change.  I knew that the file should remain deleted, so I chose that
option.  Then Mercurial responded with

  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
  (branch merge, don't forget to commit)

After committing, I modified another file on stable and merged again.
At this point, the merge proceeded cleanly because the conflict with
the deleted file had already been resolved by the previous merge.
That's nice, as those only have to be dealt with once, not multiple
times as we move forward.  It would only come up again if a 
additional change was made on the stable branch to the file that no
longer exists on default.

At this point I would be willing to switch to this new workflow and
see how it goes.

We are also due for a new point release.

I'll try to look at the diffs between 3.4.0 and the current default
sources and see if I can spot anything that would introduce a binary
incompatibility.  If not, then maybe it would be OK to go with the
current default as 3.4.1.  After that, we should be more conservative
about what is checked in to the new stable branch.

Comments?

Thanks to Jordi for pressing this issue again.  I agree that this
workflow should be much simpler for managing releases than having two
separate branches and transplanting.  Another big advantage is that if
we are conservative with the changes that are applied to the stable
branch, then it should be ready to release at almost any time.  So
making point releases should just be a matter of deciding when they
should happen and not require a lot of extra work tracking down,
evaluating, and applying patches from default to the release branch.

jwe