Document "MFC to" and "MFC with" commit tags

[bcr]

Looks good to me. Approved!

[ngie]

This should be added into the FreeBSD svn commit template -- thanks!

[dteske]

Can we add "MFC before:"? E.g., "If the commit should be merged before some particular branch creation, specify the branch name(s)." Example: "MFC before: RC-3". Used by bz and gjb. See revisions 285733, 285082, 285078, 285076, 259427, 259426, 185435, and 148871.

Now here comes the rub with the "X-MFC-*" versus "MFC *"...

"MFC after" and "X-MFC-after" are two different things. The former would be something like "MFC after: 2 weeks" and the latter would be either "X-MFC-after: 12.0-RELEASE" or "X-MFC-After: r123456".

E.g., "If the commit should be merged after some particular revision or branch creation, specify the revision(s) and/or branch name(s)." Example: "X-MFC-after: 12.0-RELEASE" or "X-MFC-after: r123456". Used by gjb, gavin, delphi, and cperciva. See revisions 283963, 283962, 267863, 261044, 259816, 257942, 257807, 257806, 257805, and 148871.

[emaste]

Can we add "MFC before:"?

I don't want to make this too long and would prefer to avoid special cases that have only occasional use. Right now it is unlikely "MFC before" could be automatically parsed. By its nature it will be somewhat unrestricted text, and even if we did parse it I don't think we want to build tooling to make the reminder script aware of upcoming branch / release dates.

Do you have a proposed description for MFC before?

the latter would be either "X-MFC-after: 12.0-RELEASE" or "X-MFC-After: r123456".

For this one I think the reminder script should just ignore a value it cannot parse, or even be extended to handle a revision; it would be quite convenient if MFC after: r12345 could do the right thing and send a notification after the associated revision gets merged.

[emaste]

"MFC after" and "X-MFC-after" are two different things.

That's precisely my point. X-MFC-after is being used intentionally to avoid being parsed by the MFC script, because the commit author believes the MFC reminder script will not be able to parse the value. That's distinct from X-MFC-to or X-MFC-with, where MFC to or MFC with would not cause trouble for the reminder script.

[dteske]

In D10585#219533, @emaste wrote:

Can we add "MFC before:"?

I don't want to make this too long and would prefer to avoid special cases that have only occasional use. Right now it is unlikely "MFC before" could be automatically parsed. By its nature it will be somewhat unrestricted text, and even if we did parse it I don't think we want to build tooling to make the reminder script aware of upcoming branch / release dates.

I wouldn’t want the reminder script to parse these — but rather https://mfc.kernelnomicon.org by Oleksandr Tymoshenko.

Do you have a proposed description for MFC before?

I gave one in the text you replied to (replicated below):

"If the commit should be merged before some particular branch creation, specify the branch name(s)."

the latter would be either "X-MFC-after: 12.0-RELEASE" or "X-MFC-After: r123456".

For this one I think the reminder script should just ignore a value it cannot parse, or even be extended to handle a revision; it would be quite convenient if MFC after: r12345 could do the right thing and send a notification after the associated revision gets merged.

Agreed, but I think the reminder script could also handle the branch case as well (“MFC after: release/10.0.0” — notification sent after branch is created).

If this becomes the case, we would have to document the decisioning and supported formats for the field.

E.g., perhaps strictly these (in order of preference by code; case-insensitive matching; awk regular expression format):

# A number followed by “days”, “weeks”, or “months” (with optional comment at end)
^(X-)?MFC([[:space:]]+|-)after:[[:space:]]*[[:digit:]]+[[:space:]]*(day|week|month)s?([[:space:][:punct:]].*)?$

# A comma or whitespace separated list of revision numbers (leading “r” optional; with optional comment at end)
^(X-)?MFC([[:space:]]+|-)after:[[:space:]]*(r?[[:digit:]]+[[:space:],]*)+([[:space:][:punct:]].*)?$

# A single branch name (with optional comment at end)
^(X-)?MFC([[:space:]]+|-)after:[[:space:]]*[^[:space:]]+.*$

Each regular expression supporting the three types seen in the past for completeness (again, case-insensitively):

1. MFC after:
2. X-MFC after:
3. X-MFC-after:

[dteske]

In D10585#219534, @emaste wrote:

"MFC after" and "X-MFC-after" are two different things.

That's precisely my point. X-MFC-after is being used intentionally to avoid being parsed by the MFC script, because the commit author believes the MFC reminder script will not be able to parse the value. That's distinct from X-MFC-to or X-MFC-with, where MFC to or MFC with would not cause trouble for the reminder script.

The primary people that have applied the “X-“ modifications have been release engineering folk (including myself when I did FreeBSD release engineering at VICOR).

The other thing to consider is how the releng team uses these tags to glom onto releng-specific work. You’ll notice over several years many commits with the “X-MFC-*” format but they have always been made by releng folk (e.g., cperciva, gavin, gjb, and myself over the years as we did various releng-related tasks).

Release Engineering will probably continue to use the “X-MFC-*” format for such purposes.

I am on the fence as to whether it is best to incorporate the alternate form used by releng@ folk so that the scripts glom onto them (as their format is in-fact quite known) or whether we keep the normal scripts as ignoring these (leaving them for releng purposes).