[quagga-dev 11641] Quagga processes: let's get a discussion going

Paul Jakma paul at jakma.org
Sun Oct 26 18:09:07 GMT 2014


Hi,

So, it's probably worth having a discussion about processes (and 
governance, in a followup email, later).

On processes, the canonical document has always been HACKING in CVS, now 
HACKING.tex in git. A PDF version being available from:

   http://www.nongnu.org/quagga/docs/HACKING.pdf

Which is linked to from the http://www.nongnu.org/quagga/devel.html page 
of the website.

Changes to processes ideally should be proposed on list (preferably as a 
patch to that file, but just a suggested text update would be fine too, 
for anyone not comfortable with LaTex[1]), for discussion and consensus. 
Anyone may do so. If you disagree with something, feel something is out of 
date or too onerous, please, please do so rather than suffer quietly. :)

Ultimately that document really does need to be updated to reflect what is 
expected.

---
Commit messages:

E.g. commit messages. HACKING.pdf has a set of requirements, which 
generally should be followed. Additionally, it recommends a certain 
itemised format, the point of which is to force contributors to read their 
patch and do a self-review before sending it. This format is rarely used 
by contributors anymore.

That section may need updating.

---
Code reviews

We've got a "Patchwork" instance somewhere, set up by David, which is 
pretty cool. It apparently can pick up on tags on the list. It'd be good 
to document all this in HACKING. I think David may have something in the 
works.

We could even start looking at some kind of quid pro quo system on 
reviews. E.g., the Postgresql model, where contributors are required to 
give reviews of others' patches as one of the conditions to get their own 
patch accepted.

Basically, there's a lot more people sending in contributions than there 
are people giving open public reviews, and it'd be great to fix that.


---
Patch acceptance processes

Currently acceptance of a patch is down to one of a small number of 
maintainers, based perhaps on vague, opaque criteria. (At least, HACKING 
doesn't have an objective list ;) ).

It'd be really good to fix that. In the ideal (which might not be 
achievable), we'd have an objective check-list that a maintainer could 
easily run through that would give a clear yes/no answer. Integrating 
patches would require 0 discretion or judgement on the part of the 
maintainer.

How do we achieve that, or at least work towards it? Require X good 
reviews from at least Y independent contributors, and no more than Z 
NACKs? (X == 2, 3, 4 ...? Y = 0, 1, 2? Z = 0, 1, ..?)

How should this process interact with code-review?

How can we and/or should we make this a more devolved and objective 
process? Please pitch in!

---
Authorship claims

tl;dr: If we really need legally binding declarations, beyond what can be 
inferred from people contributing code to a project with a big COPYING 
file and legal headers on pretty much every file, then I don't think 
signed-off-by provides it, and other options need to be looked at. (I 
don't think it's needed - it just seems pure overhead).

Some people like to add "Signed-off-by" to their commit messages. Which 
suggests either some are worried about authorship, or this practice is 
just being cargo-culted from elsewhere.

If we're worried about legal issues, I'm not at all convinced 
signed-off-by has much meaning (Linus invented it mostly to head off much 
worse processes - i.e. it was solving a social problem for Linus, more 
than a legal one; and it wouldn't have done anything for the SCO cases 
either). Particularly as we've not documented it, and contributors who've 
not added this line in the past have had replies of "Please add 
signed-off-by" but without being told *why*. Given how things stand, it 
would be hard to demonstrate with certainty that people had agreed to 
anything based on that line.

If declarations are required, several more meaningful methods are 
available. E.g., keep a file in the git repo with some text, and ask for a 
1-time patch from contributors to update that file with their name and 
email to show their assent. Another option would be require that commit 
messages follow a certain template. The template could have sections for 
each major thing we really want from contributors (what testing was done? 
What bugs are fixed? By submitting this you agree .....). See footnote 2 
for an example.

If declarations are required, what do we do about contributions without 
them? E.g. drive-by patches, or changes found in trees of 3rd parties who 
don't care to submit stuff themselves? This hasn't been made clear.

If we wished, and declarations are required, we could choose to make such 
a process apply only to corporate contributors, as the Samba project does.

That is, if we even need such a declaration at all. It should be perfectly 
clear to anyone with half a brain that you need to have the right to 
contribute code before you contribute it. Those who do not realise this 
are unlikely to be thwarted by a trivial line of text that is easily 
copied. We are not protected from such people.

If someone did, unintentionally or through malice, sneak other people's 
work in, we should know who it is, regardless of signed-off-by. That's 
what the Author field is for after all. Other authors should be listed in 
the commit body. (Signed-off-by can't be relied on for that, given current 
use, so it doesn't add anything there).

If anything can protect the Quagga project in such an event, other than 
knowing who to point the finger at, it is being seen to be absolutely 
scrupulous about honouring every copyright claim we know of that could 
reasonably be thought to apply.

For corporates for whom this might matter, it'd be useful to double check 
with your legal counsel.


---
1. make HACKING.pdf should work. You need LaTeX and TeX installed, which 
you need most of anyway to build the docs/.


2. E.g., an example template (IANAL, like Linus):

<Replace with short,max 54-char description, starting with "topic: ">

OUTLINE OF CHANGE:

<Replace with a high level outline of the motivation for this change. What 
bug did it fix, what problem or use case is being addressed and why is it 
important? How does this change address them? Does it have limitations?


DETAILED DESCRIPTION OF CHANGE, IF APPLICABLE:

<For non-trivial changes, here is where you should give a detailed 
description of how the change is implemented. If you wish, using the 
itemised format giving in the HACKING file>.


WHAT TESTING WAS DONE?:

<What did you test? What was not tested? What confidence can you have? 
What was the methodology, so that others can replicate? Ideally, your 
answer should be that the change comes with unit-tests that cover your 
changes and more>


WHO HAS AUTHORED THIS PATCH?:

<please list all possible individuals who may have authored this patch, by
name and contact details, e.g. email>


DETAILS OF THE EMPLOYER AND CONTRACTED PARTIES OF THE AUTHORS:

<Please list all known parties with whom the authors may have contractual 
obligations that might ever be applicable to this code>


PLEASE DETAILS OF ALL OTHER PARTIES WHO MAY HAVE A COPYRIGHT INTEREST:

<Please provide details of any other parties who may have a copyright 
interest in this patch. E.g., because portions of code in this 
contribution are licensed from others, or because this contribution relies 
on 3rd party libraries. Please give full details of how that other party 
has a copyright interest>


By submitting this patch, you each of the authors acknowledge that you 
have read version $X of Quagga's HACKING.pdf file. You acknowledge that 
you have the right to contribute this change under whichever applicable 
licensing terms, which generally is as detailed in the COPYING file. You 
acknowledge that you have filled out the above template in good faith and 
to the fullest of your knowledge.

Please have each author indicate their agreement to the preceding 
paragraph by adding their name and contact details, or a signed-off-by 
line, here below:


regards,
-- 
Paul Jakma	paul at jakma.org	@pjakma	Key ID: 64A2FF6A
Fortune:
The truth of a proposition has nothing to do with its credibility.  And
vice versa.




More information about the Quagga-dev mailing list