From e89be1016af2a3f8a58ad027967868c362d57bc1 Mon Sep 17 00:00:00 2001
From: Christoph Groth <christoph.groth@cea.fr>
Date: Fri, 6 Sep 2013 20:36:12 +0200
Subject: [PATCH] partial rewrite of CONTRIBUTE
---
CONTRIBUTE | 98 ++++++++++++++++++++++------------------
LICENSE | 2 +-
doc/source/pre/index.rst | 2 +-
3 files changed, 57 insertions(+), 45 deletions(-)
diff --git a/CONTRIBUTE b/CONTRIBUTE
index 97b41e9..5677a69 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -2,55 +2,55 @@
Contributing to Kwant and reporting problems
============================================
-We view Kwant as not just a package with fixed functionality, but also as a
-framework to implement 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 planning to extend it.
-
-We welcome both external contributions that are well-integrated with Kwant's
-core functionality, such as new solvers type, or algorithms for calculation of
-other observables, as well as code modules that are relatively independent but
-useful with Kwant (such as the random matrix theory module `kwant.rmt`). We
-also welcome contributions to the reference documentation and the tutorial. It
-is also possible to add complete tutorial sections that illustrate a physical
-phenomenon using Kwant.
-
-The complete development history of Kwant is `publicly available
-<http://git.kwant-project.org/kwant>`_. Any external contribution will be
-clearly marked as such, and papers where it is described (if any) will be
-properly mentioned. Contact us if you are interested in submitting a
-contribution.
-
-When you encounter a bug, first try to reproduce it with as simple of a system
-as possible. Double-check with Kwant documentation that what you observe is
-actually a bug in Kwant. Then please email the bug report the Kwant `mailing
-list <mailto:kwant-discuss@kwant-project.org>`_. A bug report should contain
-the steps required to reproduce the bug, preferably with a simple script that
-reproduces the bug attached. It should also include a description of the bug
-(i.e. what exactly goes wrong).
-
-Technical advice
-----------------
+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.
-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.)
+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. A mailing list TODO: add link (also
+usable through a web interface (TODO: add link) ) is available for discussions.
-It is best to base your development on the latest version of Kwant. ::
+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 :doc:`suggested
+acknowledgements <citing>`. The complete development history is available
+through a `web interface <http://git.kwant-project.org/kwant>`_.
- git clone http://git.kwant-project.org/kwant
+Reporiting bugs
+---------------
-To work on Kwant itself it is useful to build it in-place so that it does not
-have to be re-installed after each change. This can be done with the following
-command ::
+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 mailing list. (TODO: tell how).
- python setup.py build_ext -i
+If the problem is not known yet, please email a bug report to the `Kwant mailing
+list <mailto:kwant-discuss@kwant-project.org>`_. A report should contain:
-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 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.
+
+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 modify the code, and build Kwant and the documentation as described
+in the :doc:`installation instructions <install>`.
Some things to keep in mind:
@@ -64,3 +64,15 @@ Some things to keep in mind:
* Write tests for all the important functionality you add. Be sure not to
break existing tests.
+
+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.
diff --git a/LICENSE b/LICENSE
index ae94f00..14fa11f 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,5 +1,5 @@
=============
-Kwant License
+Kwant license
=============
(This license applies to all files of this distribution except those within the
diff --git a/doc/source/pre/index.rst b/doc/source/pre/index.rst
index 91f0ca5..40d4c4b 100644
--- a/doc/source/pre/index.rst
+++ b/doc/source/pre/index.rst
@@ -9,5 +9,5 @@ Preliminaries
install
authors
citing
- license
contribute
+ license
--
GitLab