-
Christoph Groth authoredChristoph Groth authored
community.txt 9.83 KiB
Getting help, contributing and reporting problems
=================================================
General mailing list
--------------------
The `kwant-discuss
<https://mailman-mail5.webfaction.com/listinfo/kwant-discuss>`_ mailing list is
the main public communication platform for anything related to Kwant: questions,
bug reports, discussions, and announcements. You can use it in various ways:
- .. raw:: html
<p><form id="searchgmane" method="get" action="http://search.gmane.org/">
<input type="text" name="query" size=25 value="Your query" onblur="if (this.value == '') {this.value='Your query'}" onfocus="if (this.value == 'Your query') {this.value=''}" />
<input type="hidden" name="group" value="gmane.comp.science.kwant.user" />
<input type="submit" value="Search kwant-discuss" />
</form></p>
- .. raw:: html
<form method=post action="https://mailman-mail5.webfaction.com/subscribe/kwant-discuss">
<input type="text" name="email" size=25 value="Your email address" onblur="if (this.value == '') {this.value='Your email address'}" onfocus="if (this.value == 'Your email address') {this.value=''}" />
<input type="submit" name="email-button" value="Subscribe to kwant-discuss" />
</form>
… and receive new messages with your regular email. (Use the `kwant-discuss options page <https://mailman-mail5.webfaction.com/options/kwant-discuss>`_ to unsubscribe.)
- Follow the list through a web interface: `kwant-discuss on Gmane <http://dir.gmane.org/gmane.comp.science.kwant.user>`_ or
`kwant-discuss on Mail-archive <https://www.mail-archive.com/kwant-discuss@kwant-project.org/>`_.
Gmane allows to write new messages (action: post) and to reply (action: followup).
Both Gmane and Mail-archive provide RSS feeds.
- Send a message directly to kwant-discuss@kwant-project.org. (If you are not
subscribed, it is not guaranteed that any followups will reach you by email,
so you should ask to be CCed.)
Development list
----------------
Those who are interested (or would like to participate) in the further
development of Kwant are invited to subscribe to the `kwant-devel
<https://mailman-mail5.webfaction.com/listinfo/kwant-devel>`_ mailing list.
This is the place for technical discussions about changes to Kwant.
Please do not send bug reports to this list but rather to kwant-discuss.
Kwant-devel works in the same way as kwant-discuss:
- .. raw:: html
<p><form id="searchgmane" method="get" action="http://search.gmane.org/">
<input type="text" name="query" size=25 value="Your query" onblur="if (this.value == '') {this.value='Your query'}" onfocus="if (this.value == 'Your query') {this.value=''}" />
<input type="hidden" name="group" value="gmane.comp.science.kwant.devel" />
<input type="submit" value="Search kwant-devel" />
</form></p>
- .. raw:: html
<form method=post action="https://mailman-mail5.webfaction.com/subscribe/kwant-devel">
<input type="text" name="email" size=25 value="Your email address" onblur="if (this.value == '') {this.value='Your email address'}" onfocus="if (this.value == 'Your email address') {this.value=''}" />
<input type="submit" name="email-button" value="Subscribe to kwant-devel" />
</form>
(Use the `kwant-devel options page <https://mailman-mail5.webfaction.com/options/kwant-devel>`_ to unsubscribe.)
- There exist web interfaces: `kwant-devel on Gmane <http://dir.gmane.org/gmane.comp.science.kwant.devel>`_ and
`kwant-devel on Mail-archive <https://www.mail-archive.com/kwant-devel@kwant-project.org/>`_.
Both provide RSS feeds, Gmane also allows posting through the web interface.
- Message can be sent directly to kwant-devel@kwant-project.org. (If you are not
subscribed, it is not guaranteed that any followups will reach you by email,
so you should ask to be CCed.)
Announcements (low-volume)
--------------------------
This read-only list is reserved for important announcements like new releases of
Kwant. Only a few messages will be sent per year. These announcements will be also posted on the main mailing list, so there is no need to subscribe to both lists. We recommend every user of Kwant to subscribe at least to this list in order to stay informed about new developments.
- View archives: `kwant-announce on Gmane <http://dir.gmane.org/gmane.comp.science.kwant.announce>`_ or `kwant-announce on Mail-archive <https://www.mail-archive.com/kwant-announce@kwant-project.org/>`_. Both Gmane and Mail-archive provide RSS feeds.
- .. raw:: html
<form method=post action="https://mailman-mail5.webfaction.com/subscribe/kwant-announce">
<input type="text" name="email" size=25 value="Your email address" onblur="if (this.value == '') {this.value='Your email address'}" onfocus="if (this.value == 'Your email address') {this.value=''}" />
<input type="submit" name="email-button" value="Subscribe to announcements" />
</form>
(Use the `kwant-announce options page <https://mailman-mail5.webfaction.com/options/kwant-announce>`_ to unsubscribe.)
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 the problem is not known yet, please send a bug report to
kwant-discuss@kwant-project.org. A report should contain:
* The versions of software you are using (Kwant, Python, operating system, etc.)
* A description of the problem, i.e. what exactly goes wrong.
* 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://git.kwant-project.org/kwant>`_.
If you plan to contribute, it is best to coordinate with us in advance either
through the general mailing list kwant-discuss@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 http://git.kwant-project.org/kwant
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
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
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.