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

Paul Jakma paul at jakma.org
Mon Oct 27 09:29:58 GMT 2014

Hi Vincent,

The source is HACKING.tex, just edit that. Many people will wanto to use a 
LaTeX specific editor (TexStudio, Texmaker, LaTeXila, etc) or something 
with some knowledge of LaTeX (Emacs has something I think, Eclipse too).

Latexila is the one I'd use on Linux.

Otherwise, just suggest text, as you've done. :) If you want to expand the 
below a bit? Otherwise I'll come back and have a go this afternoon.



On Mon, 27 Oct 2014, Vincent JARDIN wrote:

> Hi Paul,
> How to edit this PDF, do you want to be the editor?
> few comments:
> Add a section about patchwork:
>  - http://patchwork.quagga.net/project/quagga/list/
> It is important to remind that patchwork must remain clean:
>     + login / set under review / then send a ack't or reviewed-by
> Add a section about how to contribute:
>  - fairness with contributors:
>     + In order to increase the visibility of some contributions, play the 
> fairness of reviewing patches from others which are on patchwork. The more 
> someone helps other patches to be accepted, the better their patches should 
> be accepted
>     + process for fair contributors: git clone, use pw-client to get a 
> patch, apply it, ack't it by email
>  - for maintainers:
>     + a section about, get the patch from patchwork (using pw-client, apply 
> it, git push)
> see: http://savannah.gnu.org/maintenance/UsingGit/ ; but it does not have a 
> KIS section.
> Thanks for rising the topics again,
>  Vincent
> On 26/10/2014 19:09, Paul Jakma wrote:
>> 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: ">
>> <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?
>> <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 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>
>> <please list all possible individuals who may have authored this patch, by
>> name and contact details, e.g. email>
>> <Please list all known parties with whom the authors may have
>> contractual obligations that might ever be applicable to this code>
>> <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,
> _______________________________________________
> Quagga-dev mailing list
> Quagga-dev at lists.quagga.net
> https://lists.quagga.net/mailman/listinfo/quagga-dev

Paul Jakma	paul at jakma.org	@pjakma	Key ID: 64A2FF6A
Father Ted: That money was just resting in my account!

More information about the Quagga-dev mailing list