CONTRIBUTING.md

[eugeneia]

Having a CONTRIBUTING.md (this file will be displayed by GitHub when creating a PR for the first time) would help maintainers and contributors by providing an initial “common ground”. This came up a couple of times in previous discussions and I want to create this discussion to figure out what should be communicated in the file. Eventually, when everybody is happy I would open a PR that formulates the results.

I understand that there are plenty of things that could be useful to have written down in a CONTRIBUTING.md, but on the other hand I feel like it should be kept concise to reduce reading-overhead. Possible influences for CONTRIBUTING.md include:

• Git merge network: past, present, and near future #746 Working with Github Pull Requests #725 Working with GitHub Issues #702 - We should probably explain in a few sentences how the merge workflow works roughly, and what is expected of PR authors and what they can expect from maintainers
• Clarify copyright notice policy #729 - “Copyright notices belong into src/COPYRIGHT; copyright notices in others files are rejected.”
• Document a coding style for use of object-orientation in Snabb #740 - Eventually, we should document coding styles when they emerge and point to that documentation
• Point to the documentation guide

Anything I missed, any new ideas? Feedback from everybody is welcome including @kbara, @wingo and @lukego.

[kbara]

All of that sounds reasonable to me, at least in light of the way the discussion on copyright notices in source files has gone in this project specifically. We should avoid ever making the coding styles document too heavy-weight.

[lukego]

I agree that we want a CONTRIBUTING.md but I think it should be a half-page of helpful information to make contributors understand the process of landing code in Snabb.

Let's please avoid lots of rules and policies that need active policing. My view is that consistency breeds consistency with the code and documentation. If we start sending PRs that improve consistency then this will become a pattern and the results will speak for themselves. A picture says a thousand words, etc.

[lukego]

Generally when somebody contributes code to Snabb I think it would be productive to assume that:

1. They have done something valuable that we can benefit from as a community.
2. They are smarter than we are.
3. They have other important things to attend to.

On the other hand we know the Snabb code and workflow better than they do. We can help people understand how their code will be merged, make technical suggestions that we think people will appreciate, flag important issues that should be addressed before the code is merged, and make unsurprising corrections ourselves ("I removed the copyright line and added a license line as described in CONTRIBTING.md").

I think we need to be very careful to respect the time and intelligence of the contributors to the project and so e.g. not insist that they read the essay "L. Gorrie: Treatise on the nature of simplicity in software development" before they can be considered qualified to contribute to Snabb.

I need to spend some time reflecting on whether I am following these guidelines in practice...

[lukego]

... putting my money where my mouth is: I swept through and added license references to the entire code base on #729. I hope that doing this consistently will establish the idiom i.e. people will notice that every existing file has such a notice and tend to follow suit.

[petebristow]

"L. Gorrie: Treatise on the nature of simplicity in software development" sounds quite an interesting read where can I find a copy!

[petebristow]

I'd like to see a 'cheat sheet' of guidance be put together, and ideally linked to or included in CONTRIBUTING.md. Things like

• PR against master ?
• 3 space indent
• No tabs allowed
• Expect someone to pick up CRs after X days, chase after that if it's important to you ?
• We use snake case ?
• @eugeneia shared some git aliases for easy PR merging.

This is coming from the perspective of working on multiple projects each with there own set of preferences and a cheat sheet would help context switches. CONTRIBUTING.md is also linked from the PR creation page so is a nice reminder to self check.

[eugeneia]

Good points! I have created #904 to cover the first four points. (I am not too certain about the others).