diff --git a/conf.py b/conf.py index 1b740fc66c07bbd0b0e68b08456c207af8434d5f..dd3110c141ded1e89719f5da97ece3c7b9f112b8 100644 --- a/conf.py +++ b/conf.py @@ -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>" diff --git a/content/community.rst b/content/community.rst index 866fe4a5b7c8234cdc3a83125a703877fffb42bf..f75e8f6aa16151c3a2f4ba60e643743498d7f563 100644 --- a/content/community.rst +++ b/content/community.rst @@ -1,5 +1,5 @@ -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. diff --git a/content/contribute.rst b/content/contribute.rst new file mode 100644 index 0000000000000000000000000000000000000000..d49fe5fbd0c4c5d6c177be639ef2a05eb24652d0 --- /dev/null +++ b/content/contribute.rst @@ -0,0 +1,168 @@ +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. diff --git a/htaccess-apache b/htaccess-apache index f9ebc50f37a8aafc5da295a9c826b0c18e623dc4..3f796860e1129031de06de170c492c07e60b2b75 100644 --- a/htaccess-apache +++ b/htaccess-apache @@ -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