Merge pull request #462 from FreifunkBremen/contribution-guidelines

RFC: Add contribution guidelines

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+Contribution Guidelines
+=======================
+
+Because Gluon is such a universal software package that is used by several
+different communities with different expectations and requirements, it is both
+essential and difficult to have contributions from the communities. While they
+are sometimes necessary to adapt Gluon to the needs of the communities, they
+also have to be adaptable enough to fit as many needs as possible. On the other
+hands, very special needs are better addressed in packages in [community
+repositories], because the Gluon maintainers would not use or test them and
+thus couldn't do their "job" of maintaining them.
+
+To ease the work for the maintainers and to reduce the frustration of
+contributors, please adhere to the following guidelines:
+
+Discuss first, build later
+--------------------------
+If you have some non-trivial enhancement like a new package, some modification
+of what is announced by a node, it is often best to first discuss the precise
+solution first. The maintainers might have hints as to how a solution could be
+implemented easiest, point out solutions how the same thing can already be done
+using other parts or why the proposed change breaks other parts of the system.
+They might even refuse the idea altogether - after all, they have to sleep well
+after merging the changes, too.
+
+The preferred way to discuss in the IRC channel ([#gluon] on irc.hackint.org)
+or on the [mailing list], however, you can also open a new issue on Github to
+discuss there.
+
+Develop on top of master
+------------------------
+If you are not developing something specific to a release (like for example a
+security fix to a feature that got completely rewritten since the release),
+develop it on top of the master branch. New features and even feature changes
+aren't usually backported to old releases, but will be included in the upcoming
+release, which will be built from master.
+
+Use descriptive commit messages
+-------------------------------
+If you modify a single package, start the first line of your commit message
+with the package name followed by a colon. The first line should be enough to
+identify the commit a week later and still know roughly what it did. If you
+fix some bug, detail in the remaining commit message exactly how it could be
+triggered and what you did to fix it. If in question, have a glance at the
+existing commit messages to get the idea.
+
+Squash commits
+--------------
+Most changes are trivial enough to fit in one single commit in order to not
+clutter the history. While developing a new feature, you are free to use
+multiple commits, but if your feature is to be merged, reduce the number of
+commits to a minimum. Even huge feature introductions like the 802.11s mesh
+(commit 2a93c58) fit into a single commit.
+
+If you developed your change in multiple smaller commits, you can easily
+[squash] those before opening the pull request. While discussing, it is okay to
+do your changes using `git commit --amend` and force-push them to your head of
+the pull request. This way, your change always consists of only one commit and
+can be merged in the instant everybode is content with the whole thing.
+
+
+[community repositories]: http://gluon.readthedocs.org/en/latest/user/site.html#packages
+[#gluon]: irc://irc.hackint.org/gluon
+[mailing list]: mailto:[email protected]
+[squash]: https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits