Commit a84668e0 authored by Christoph Groth's avatar Christoph Groth
Browse files

expand "how to contribute", make it an own page

parent 19557a87
......@@ -129,6 +129,8 @@ NAVIGATION_LINKS = {
"<span class='hidden-xs'>documentation</span>"),
("/community.html", "<i class='glyphicon glyphicon-comment visible-xs-inline-block'></i>"
"<span class='hidden-xs'>community</span>"),
("/contribute.html", "<i class='glyphicon glyphicon-wrench visible-xs-inline-block'></i>"
"<span class='hidden-xs'>contribute</span>"),
("/authors.html", "<i class='glyphicon glyphicon-user visible-xs-inline-block'></i>"
"<span class='hidden-xs'>authors</span>"),
("/cite.html", "<i class='glyphicon glyphicon-edit visible-xs-inline-block'></i>"
......
Getting help, contributing and reporting problems
=================================================
Getting in touch with the Kwant community
=========================================
General mailing list
--------------------
......@@ -114,14 +114,16 @@ Kwant. Only a few messages will be sent per year. These announcements will be
Reporting bugs
--------------
If you encounter a problem with Kwant, first try to reproduce it with as simple
a system as possible. Double-check with the documentation that what you observe
is actually a bug in Kwant. If you think it is, please check whether the problem
is already known by searching the general mailing list. (You may use the search
box at the top of this page.)
If you encounter a problem with Kwant, first try to reproduce it with as
simple a system as possible. Double-check with the documentation that what
you observe is actually a bug in Kwant. If you think it is, please check
whether the problem is already known in the `Kwant bugtracker
<https://gitlab.kwant-project.org/kwant/kwant/issues?label_name=bug>`_. It can
be also a good idea to search the general mailing list. (You may use the
search box at the top of this page.) If you are unsure whether something is a
bug or not, please do ask on the mailing list.
If the problem is not known yet, please send a bug report to
kwant-discuss@kwant-project.org. A report should contain:
A useful bug report should contain:
* The versions of software you are using (Kwant, Python, operating system, etc.)
......@@ -129,98 +131,3 @@ kwant-discuss@kwant-project.org. A report should contain:
* Enough information to reproduce the bug, preferably in the form of a simple
script.
Contributing
------------
We see Kwant not just as a package with fixed functionality, but rather as a
framework for implementing different physics-related algorithms using a common
set of concepts and, if possible, a shared interface. We have designed it
leaving room for growth, and plan to keep extending it.
External contributions to Kwant are highly welcome. You can help to advance
the project not only by writing code, but also by reporting bugs, and
fixing/improving the documentation.
If you have some code that works well with Kwant, or extends it in some useful
way, please consider sharing it. Any external contribution will be clearly
marked as such, and relevant papers will be added to the list of `suggested
acknowledgements </citing.html>`_. The complete development history is also
made available through a `web interface <http://gitlab.kwant-project.org/kwant/kwant/commits/master>`_.
If you plan to contribute, it is best to coordinate with us in advance either
through the development mailing list kwant-devel@kwant-project.org, or directly at
authors@kwant-project.org for matters that you prefer to not discuss publicly.
How to contribute
.................
We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
development of Kwant. If you are new to Git, we invite you to learn its basics.
(There's a plethora of information available on the Web.) Kwant's Git
repository contains not only the source code, but also all of the reference
documentation and the tutorial.
It is best to base your work on the latest version of Kwant::
git clone https://gitlab.kwant-project.org/kwant/kwant.git
Then you can build Kwant and the documentation as
described in the `build instructions
</doc/1/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
formatting conventions. We generally follow the `"Style Guide for Python
Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
`NumPy's "Docstring Standard"
<http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
`Python's "Docstring Conventions"
<http://www.python.org/dev/peps/pep-0257/>`_.
* 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 ::
python setup.py build_ext -i --cython
The ``kwant`` subdirectory of the source distribution will be thus turned into
a proper Python package that can be imported. To be able to import Kwant from
within Python, one can either work in the root directory of the distribution
(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
somewhere in the Python search path to the the package subdirectory.
The option ``--cython`` enables the translation of .pyx files into .c files.
It is only needed if any .pyx files have been modified.
Contributing to Kwant
=====================
We see Kwant not just as a package with fixed functionality, but rather as a
framework for implementing different physics-related algorithms using a common
set of concepts and, if possible, a shared interface. We have designed it
leaving room for growth, and plan to keep extending it.
Contributions to Kwant are highly welcome. You can help the project not only
by writing code, but also by reporting bugs, and fixing/improving the
website and the documentation.
Where help is needed
--------------------
The `Kwant issue tracker
<https://gitlab.kwant-project.org/kwant/kwant/issues>`_ serves to track bugs
in Kwant, but most issues are in fact ideas for enhancements. The issues are
categorized with labels, so that it is possible to view `all the “easy” issues
<https://gitlab.kwant-project.org/kwant/kwant/issues?label_name=difficulty%3A+easy>`_
for example.
Please do feel free to enter new issues yourself. If you are unsure about
some aspect It may be a good idea to discuss your idea on the development
mailing list kwant-devel@kwant-project.org before filing an issue.
If you already have some code that extends Kwant in a useful way, please
consider sharing it. If your extension fits well with Kwant and is of wide
enough interest, we will be happy to include it into Kwant proper. For more
specialized cases, we will find a solution as well. (We could, for example,
add a list of Kwant-related modules to this website.) In any case, external
contributions will be clearly marked as such, and relevant papers will be
added to the list of `suggested acknowledgements </cite.html>`_.
Getting the source code
-----------------------
The source code of released versions of Kwant is available for `download
<http://downloads.kwant-project.org/kwant/>`_. You can follow the development
through the `Kwant page of our GitLab instance
<https://gitlab.kwant-project.org/kwant/kwant>`_. The `Git
<http://git-scm.com/>`_ repository of Kwant can be cloned directly with the
command ::
git clone https://gitlab.kwant-project.org/kwant/kwant.git
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.
Setting up for development
--------------------------
When working with the Kwant source, regular `build instructions
</doc/1/pre/install.html#building-and-installing-from-source>`_ apply. It
would be tiresome, however, to have to reinstall the modified Kwant after each
modification.
One easy way to avoid this is to build in-place so that there is no need to
reinstall after each change. This can be done with the following command ::
python3 setup.py build_ext -i
No further installation is necessary. The “inner” ``kwant`` subdirectory has
been turned into a proper Python package that can be imported from the “outer”
directory, i.e. the directory where ``setup.py`` is located. Any script
inside that directory that imports Kwant will get the modified version. (To
be able to import the modified Kwant from another directory one can create a
symbolic link to the package.)
The above ``build_ext`` command does not have to be rerun when a Python file
is modified. Recompilation is only necessary whenever a Cython file
(``.pyx``) has been changed.
Modifying the source code
-------------------------
We recommend that you keep each of your changes to Kwant on a separate “topic
branch” that starts at *master*. Try to not mix up unrelated changes in a
single branch. To create a topic branch, use the command::
git checkout -b my_topic master
Now you can begin to implement your idea. As you go, register your changes
with Git as explained, for example, in the `Pro Git book
<https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository>`_
that is freely available online.
Once you feel that you would like to show your work to other interested people
(because you would like to receive feedback, or because you consider it
ready), it's time to inspect your branch. Run ``git status`` to make sure
that you have committed all of your changes, then use a tool like ``gitk`` to
view your branch.
In the following two methods to share your commits are described. The first
one requires only minimal setup, the second will be familiar to people who use
the popular GitHub service.
Method 1: Sending patches to the development mailing list
.........................................................
The simplest way to let the community know about your change is to send
patches to the mailing list.
Run the command ::
git format-patch origin/master
This will create “patch” file for each commit on your branch. Now simply send
these patches as email attachments to kwant-devel@kwant-project.org, together
with an explanation of your idea. You do not have to be subscribed to the
mailing list.
(Or, even better, use ``git send-email`` as shown in 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/>`_.)
Method 2: Using the Kwant GitLab instance
.........................................
Go the `GitLab page of the official Kwant repository
<https://gitlab.kwant-project.org/kwant/kwant>`_. Since you do not have write
access to this repository, you have to create an own “fork” of it by clicking
on the button just right of the “star” button.
You created a public copy of the Kwant repository that is controlled by you.
Add it as a remote repository to the clone of Kwant on your computer::
git remote add own https://gitlab.kwant-project.org/<USERNAME>/kwant.git
You can copy your own version of the above URL from the main page of your
repository. (If you know about SSH, you may also prefer to upload your public
ssh key to GitLab and to use SSH as transport.) The string ``own`` is the
local name you give to the remote, it can be anything.
Now you can push your topic branch to your repository::
git push own my_branch
This will make your branch appear in GitLab. Now you can let us know about
your branch by `creating a merge request in GitLab
<https://gitlab.kwant-project.org/help/workflow/forking_workflow.md>`_ or by
sending a message to kwant-devel@kwant-project.org.
Coding style
------------
* Please keep the code consistent by adhering to the prevailing naming and
formatting conventions. We generally respect the `"Style Guide for Python
Code" <http://www.python.org/dev/peps/pep-0008/>`_. For docstrings, we
follow `NumPy's "Docstring Standard"
<http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
`Python's "Docstring Conventions"
<http://www.python.org/dev/peps/pep-0257/>`_.
* 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.
......@@ -33,5 +33,4 @@ RewriteRule ^(.*)/$ /$1 [R=301,L]
Redirect 302 /2015-survey https://docs.google.com/forms/d/1j0LiFdZLjvfwoEyg5FML6z3sFKqV3Ar1mWReonYhatA/viewform
Redirect 302 /contact /authors
Redirect 302 /citing /cite
Redirect 302 /contribute /community
Redirect 302 /download /install
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment