|
|
@@ -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:gluon@luebeck.freifunk.net
|
|
|
+[squash]: https://www.git-scm.com/book/en/v2/Git-Tools-Rewriting-History#Squashing-Commits
|
Jan-Philipp Litza