Add contribution guidelines
This commit is contained in:
parent
f5bef2ab01
commit
c6b551aeeb
65
CONTRIBUTING.md
Normal file
65
CONTRIBUTING.md
Normal file
@ -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
|
Loading…
Reference in New Issue
Block a user