[riot-devel] Pull request procedure

Kaspar Schleiser kaspar at schleiser.de
Fri Aug 21 11:13:49 CEST 2015


Hey,

On 08/21/15 11:01, Emmanuel Baccelli wrote:
> One argument for decently documented/explained code is

Do I sound like I want to write complex, undocumented code?

I just don't agree with a "rule" requiring a PR to have perfect
documentation before even opening it.

Documented code (might be self-documenting) is a baseline that we all
agree with. Having that as a rule for PRs is IMHO overregulation.

Say I write a complex piece of code, add comments where I find them
necessary. As I wrote the complex beast, I find everything "very clear".
So I open the PR, and  someone says "sorry I don't understand and
documentation is missing".

So I improve documentation and try to clarify things until the reviewers
are happy.

That's how we've been doing things as far as I can remember.

Now of what use is a rule requiring "documentation that makes things
very clear"? What does "very clear" mean?

Kaspar


More information about the devel mailing list