Branch point/branch point tags

[Warner Losh]

On Fri, Feb 5, 2021 at 1:59 PM John Baldwin <jhb at freebsd.org> wrote:

> On 2/5/21 12:03 PM, Warner Losh wrote:
> > On Fri, Feb 5, 2021 at 11:50 AM John Baldwin <jhb at freebsd.org> wrote:
> >
> >> On 2/5/21 10:16 AM, Glen Barber wrote:
> >>> On Fri, Feb 05, 2021 at 12:02:52PM -0600, Kyle Evans wrote:
> >>>> Hello!
> >>>>
> >>>> For some context: I received an e-mail from the commit about
> >>>> releng/13.0 being branched ("git: 638e531019fd - releng/13.0 - Branch
> >>>> releng/13.0"), but it's unfortunately impossible to tell based on
> >>>> e-mail context which commit it branched off on. Notably, commit races
> >>>> happen and re@ isn't obligated to pick 'the latest at that exact
> time'
> >>>> as far as I'm aware -- presumably they have carte blanche to pick
> >>>> whichever commit they feel is a good choice.
> >>>>
> >>>> We didn't really have this issue with svn because there was a single
> >>>> commit that announced both implicitly in the addition summary as well
> >>>> as explicitly which commit was chosen as the branch point (referencing
> >>>> "svn commit: r339434 - stable/12").
> >>>>
> >>>> We can of course discover what we care about in the git world by
> >>>> clicking on the link to go to cgit and exploring the parent, but this
> >>>> is decidedly not always convenient.
> >>>>
> >>>> I had thought of one solution, but it's not great; adding the parent
> >>>> commit hash to the mail when a new ref is pushed. That imposes some
> >>>> weird limitations that remove some of the benefit of git, e.g., re@
> >>>> would have to push the branch in the first commit then push any
> >>>> follow-up unless we can slap it on 'the first commit in a push that
> >>>> created a new ref'. This is kind of silly when they can just prepare
> >>>> everything that needs to be done and push it with confidence in a
> >>>> single step.
> >>>>
> >>>> jhb@ pointed out on IRC another possible solution, and I'm wondering
> >>>> what the git wg and re@ think... apparently, in the dark ages that
> far
> >>>> predate me (CVS), we had something like a BP ("Branch Point") tag that
> >>>> served the same purpose.
> >>>>
> >>>> - Is this desirable information for anyone else to have?
> >>>> - Would it screw up anything we actively try to do?
> >>>>
> >>>> I imagine, for example, that re would just create an annotated
> >>>> RELENG_13_0_BP tag and push that, which would serve as the
> >>>> announcement that this is the commit for reference and perhaps also be
> >>>> good bisect targets. While `git merge-base` works well for simply
> >>>> matters, if you want to bisect from RELENG_13_0_BP to RELENG_13_1_BP
> >>>> it's definitely quicker to conjure up the well-defined tag name than
> >>>> `git bisect $(git merge-base releng/13.1 stable/13) $(git merge-base
> >>>> releng/13.0 stable/13)`
> >>>>
> >>>
> >>> I do not have any comments on the solutions here, but I will make sure
> >>> it is brought up during the next working group call.  Admittedly,
> >>> I probably should have explicitly stated releng/13.0 was branched from
> >>> stable/13, but I suppose part of me just figured it would be obvious
> >>> from a workflow perspective.  But given I am personally so familiar
> with
> >>> the workflow in this case, it was a bad assumption on my part, either
> >>> intentional or otherwise.
> >>>
> >>> That said, I will be more thoughtful of this in the future, regardless
> >>> of what solution(s) (if any) are implemented.  Thank you for pointing
> >>> this out.
> >>
> >> I don't know that we want all-caps tag names in a git world, btw.  That
> >> was just something we did in CVS (and I do think we had tags like
> >> RELENG_2_2_BP and RELENG_3_BP).  Part of the reason was that there were
> >> no changesets in CVS, so you really had to have a tag for sanity.
> >>
> >> I do think tags might be nice, e.g. if we had a stable-13-bp tag (or
> >> stable-13), then 'git describe --exclude "vendor/*"' on main would
> >> show the number of commits since 13 was branched which is more useful
> >> than what it shows now.  Similarly, on stable/13 'git describe' would
> >> now be showing the number of commits since 13.0 was branched by
> >> default.  I also think there's some merit to Kyle's argument that we
> >> can tell users 'git bisect releng-13.0-bp release/13.1' to bisect
> >> between releases.  I'm sure there's some bikeshedding that can be
> >> had about tag names (- vs _, 'stable-13-bp' vs 'stable/13-bp' vs
> >> 'bp/stable/13').
> >>
> >> In terms of sheer number of tags, I don't think this would add a ton
> >> of them (1 additional tag per stable and releng branch), and I would
> >> suggest we only start this for 13.x and not do it on older branches.
> >> We can always add this retroactively for older branches in the future
> >> if we found we really wanted/needed it.
> >>
> >
> > Do we need it? In the git world we can say stable/13..release/13.0 to get
> > from wherever on the stable/13 branch it was branched to the tip of the
> > branch. But you can also get this with 'git merge-base' as well, which is
> > much more generic than dropping arbitrary tags.
>
> True, though one of Kyle's explicit points was to avoid forcing users
> to use merge-base.  I think one thing to consider is the command line
> we tell users to use for bisecting and what is more friendly for users
> to use (who may not be git savvy).  Using merge-base is probably fine, but
> all of the examples you gave probably look a bit intimidating to a
> non-developer user who is less familiar with git.  We will probably just
> have to make sure we have some good recipes for things like "how to
> bisect between releases" because 'git bisect release/13.0 release/13.1'
> won't work
>

It won't work today with svn either. You have to know to go back to
stable/13 branch and you'd have to find the branch points for both 13.0 and
13.1, which we don't splat tags down on. You'd have to work that out by
hand as well since svn had no bisect command.


> It is true that we can always wait to see whether or not there is a need
> over time (e.g. how do users on stable@ cope with using stable/13 via
> git instead of svn) since tags can be added retroactively.
>


% git checkout release/13.1
% git bisect start
% git bisect bad
% git bisect good `git merge-base stable/13 release/13.0`

isn't terrible and generalizes well... It isn't exactly bisecting between
13.0 and 13.1, but it's close enough that the delta can be safely ignored
(last-minute changes, security advisories and engineering notices are safe
enough they shouldn't cause issues)...

I think we absolutely need to document these things, of course (as well as
my examples, which generally aren't things people would need/want to do
except occasionally). I've started the drudgery of getting things converted
from md to asciidoc and moving content into the handbook and other places
in our tree. I think a lot of the need for a tag will be driven by how good
the docs are since the commands aren't super-long... I'd expect the people
who aren't git savvy will read our docs and follow them...

I'll also note that other projects that have a similar branching structure
to ours don't explicitly tag the branch point. So there's not a design
pattern from the rest of the open source community we can easily draw upon
either.

Warner