diff --git a/content/community.txt b/content/community.txt index 27ddf22a6b514b05ca96c4f1c355d304a2b6501e..c99042c82ebadd57fec3e3925bcb382495d4157a 100644 --- a/content/community.txt +++ b/content/community.txt @@ -146,10 +146,35 @@ It is best to base your work on the latest version of Kwant:: git clone http://git.kwant-project.org/kwant -Then you can modify the code, and build Kwant and the documentation as +Then you can build Kwant and the documentation as described in the `build instructions </doc/1.0/pre/install.html#building-and-installing-from-source>`_. +The Kwant git repository has two main branches: The branch *master* +contains the development towards the next release. The branch *stable* contains +the most recent release that is considered stable, and only bugfixes are applied +to it. + +We recommend that you keep your changes on a separate `topic branch +<https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html#_topic_branches>`_ +that starts at *master*. To create such a branch, use the command:: + + git checkout -b my_topic_branch master + +Once you have something that you would like to share, let us know about it by +posting to kwant-devel@kwant-project.org. We are happy to receive useful +contributions in any reasonable way: you can send patches to the mailing list, +make your git repository available on the web (you could use a service like +github), or even directly send the file that you modified. + +The recommended way is sending patches to the mailing list. (This avoids +confusion by publishing unfinished git branches and allows code review.) See +this `example of usage +<https://kernel.org/pub/software/scm/git/docs/git-send-email.html#_example>`_ +and this `git send-email howto +<http://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/>`_, +it’s easy. + Some things to keep in mind: * Please keep the code consistent by adhering to the prevailing naming and @@ -163,6 +188,8 @@ Some things to keep in mind: * Write tests for all the important functionality you add. Be sure not to break existing tests. +* Create a logical sequence of commits with clear commit messages. + A useful trick for working on the source code is to build in-place so that there is no need to re-install after each change. This can be done with the following command ::