Talk:Development Guidelines

From flashrom
Revision as of 17:34, 14 November 2017 by Nico (talk | contribs) (demote 5-day rule to RCs with code changes)
Jump to navigation Jump to search

Hey, I'd like to propose a lot of changes here, now that we'll work with a single master branch on Gerrit. I'll leave some comments in bold & italic.

Branches

Mostly rewritten.

Historical

Till the release of flashrom 0.9.9 there was basically a single branch (trunk) where linear development happened. After 0.9.9 it was decided to switch to Git and a two branch model, a stable and a staging branch. This led to some confusion and as nobody who had access to the stable branch had the time to work on it, development continued about one year after the 0.9.9 release on a staging branch at coreboot.org. Despite its name, we strived to keep flashrom's quality and hoped that everything would be merged to stable once work continues there.

master branch

The historical staging branch was finally renamed to master. As usual there is no quality promise for the state of the code on the master branch. Even though we will try to keep the regression rate as low as possible, the main purpose of the branch is to merge new commits and make them available to a broader audience for testing.

Release branches (e.g. 1.0.x)

Branching for a new release can happen at any point in time when a commit (branch point) on master seems to be in good shape and was reasonably tested after previous invasive changes. Between the branch point and the release, every fix pushed for master for a problem that also persist on the release branch shall be backported. The same also applies after the release for the latest release branch and, optionally, for any earlier release branch that is still maintained for other reasons (e.g. part of a long term distribution).

Whenever a release branch has no further unmerged commits in queue and is not awaiting backported fixes, a release candidate (RC) can be tagged on that branch. This can also be the original branch point. The RC shall undergo extensive build tests and be publicly advertised as ready for testing. Not less than five days after the last RC that included code changes, a release can be tagged if no regressions showed up.

Release-branch names follow the pattern <major>.<minor>.x (e.g. 1.0.x). The first release of a branch is tagged v<major>.<minor>, without a point-release number (e.g. v1.0). Every following release from the same branch, will have a point-release number starting with .1 (e.g. v1.0.1).

We could add some note about stability of the first release from a branch, e.g. like Linux say that only the first point release is stable. I'd bet, though, that it won't make a difference in practice: The quality of point releases is always better, not matter how you advertise it.

I guess we should always tag the branch points as well, otherwise the version strings for builds from master would be stuck on the last branch point that actually was an RC (or v0.9.9 for now). Any suggestion for tag names? b1.0? maybe rather p1.0 (for post-1.0)? something that's not too easy to confuse with the branch name

Patch submission

Keep

Sign-off Procedure

Keep

Reviews

Maybe reword, mention where reviews may happen (I think we should ask each contributor on the ML / github if he agrees to switch to Gerrit). Btw. is there a option in github to send emails, like we have it on flashrom-gerrit?

Acked-by

Drop, everything goes through Gerrit

Adding/reviewing a new flash chip

Keep, actually TLDR; maybe move somewhere else

Committing

Replace by:

Merging to branches

Merging to branches is limited to the "flashrom developers" group on Gerrit. This means every patch reviewed somewhere else (e.g. mailing list or github) must finally be pushed to Gerrit. The following rules apply, some are already enforced by Gerrit:

  • Every commit has to be reviewed and needs at least one +2 that was not given by the commit's author.
  • Except, if a commit is authored by more than one person, each author may +2 the other author's changes.
  • Merging should not take place within less than 24 hours after the review started (i.e. the first message by a reviewer on Gerrit).
  • Finally, before hitting Submit, one is reponsible to check that all comments have been addressed, especially if there was a negative review (-1).