[coreboot] Reviving flag days

Patrick Georgi pgeorgi at google.com
Tue Apr 21 23:55:36 CEST 2015


Hi,

some of you might remember the flag days initiative, which led to some
useful information on how to keep up with upstream development while
maintaining local branches (or repos). If you don't, please look at
the marvel that is
http://coreboot.org/index.php?title=Flag_Days&oldid=10718

The short story is that for each change that required sweeping
changes, eg. a new function call that certain drivers need to
implement, a new argument to a function, or a Kconfig variable that is
retired a short blurb was written so developers could follow up.
Where practical, these could contain coccinelle patches, reducing work
for fellow developers even more.

With the switch to git, we dropped the habit.

Do we want to reestablish that routine?

A rule of thumb is that there's a flag day if a mainboard or chipset
that was copied out of the tree before your commit and submitted after
your commit needs to be adapted due to your change.

That sounds contrived, but it's actually quite common: people copy the
code for a mainboard similar to what they're working on, hack on it
for a while, then try to upstream. Chances are that there are changes
to the original mainboard code to follow up on.

My proposal on implementation is to integrate flag day docs with git:
let's create the convention that such changes come with documentation
in documentation/flagdays/, maybe keyed to the author's email address
to avoid conflicts, and some description, for example
documentation/flagdays/pgeorgi at google.com-rename-console.h-to-textout.h.md
(I don't actually want to do that rename, calm down :-) ).

>From there, a server side script can determine the commit date (which
is the effective date for when the change was submitted) and commit
id, and create a wiki page from those files.
Since I still hope that we eventually get rid of the wiki, I propose
to use plain text (.txt suffix) or markdown (.md suffix) as 'neutral'
formats. pandoc can make this into wiki syntax (or pretty much
everything else) with ease.
The same script could be used locally to generate the documentation as
well (ie. it resides somewhere below util/).
To allow for post-hoc additions of flag days, there should also be a
way to declare a commit id within the doc (eg. first line stating:
commit-id: 1a2b3c4)

If we go with this proposal (or some variant thereof), I'll take care
of the scripting and automation to generate the doc. It would be our
collective responsibility to remember when to write such docs, or to
request them to be added during review where needed.


Thoughts?
Patrick
-- 
Google Germany GmbH, ABC-Str. 19, 20354 Hamburg
Registergericht und -nummer: Hamburg, HRB 86891, Sitz der Gesellschaft: Hamburg
Geschäftsführer: Graham Law, Christine Elizabeth Flores



More information about the coreboot mailing list