From b17852119025de464e94d35b6869e38c7b80472f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sat, 30 May 2020 21:25:16 +0200 Subject: [PATCH 1/8] docs: Cleanup API policy --- doc/sphinx/introduction.rst | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index 025f36cdf75..2f6088440fc 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -522,22 +522,32 @@ report so to the developers. -Intended interface compatibility between ESPResSo versions ----------------------------------------------------------- +.. _Intended interface compatibility between ESPResSo versions: + +Intended interface compatibility between |es| versions +------------------------------------------------------ We use the following versioning scheme: major.minor.patch_level -With regards to the stability of the Python interface, we plan the following guidelines: +With regards to the stability of the Python interface, we have the following +guidelines: - * patch_level: The Python interface will not change, if only the patch_level number is different. Example: 4.0.0 -> 4.0.1. +* ``patch_level``: The Python interface will not change if only the + ``patch_level`` number is different. Example: 4.0.0 :math:`\to` 4.0.1. - * minor: There will be no silent interface changes between two versions with different minor numbers. I.e., a simulation script will not silently produce different results with the new version. The interface can, however, be extended. In important cases, the interface can change in such a way that using the old interface produces a clear error message and the simulation is terminated. Example: 4.0.1 -> 4.1.0 +* ``minor``: There will be no silent interface changes between two versions + with different minor numbers, i.e. a simulation script will not silently + produce different results with the new version. The interface can, however, + be extended. In important cases, the interface can change in such a way + that using the old interface produces a clear error message and the + simulation is terminated. Example: 4.0.2 :math:`\to` 4.1.0. - * major: No guarantees are made for a transition between major versions. Example 4.1.2 -> 5.0. +* ``major``: No guarantees are made for a transition between major versions. + Example: 4.1.2 :math:`\to` 5.0. - * No guarantees are made with regards to the development branch on GitHub. +* No guarantees are made with regards to the development branch on GitHub. - * No guarantees are made with respect to the C++ bindings in the simulation core. +* No guarantees are made with respect to the C++ bindings in the simulation core. From f56ffbf228ecf583e5272c99cb4f08c901ad40b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sat, 30 May 2020 21:41:46 +0200 Subject: [PATCH 2/8] docs: Format GNU GPL license --- Readme.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Readme.md b/Readme.md index 1f64fd52b68..928ef2415b5 100644 --- a/Readme.md +++ b/Readme.md @@ -71,21 +71,21 @@ relevant publications, as indicated in the ESPResSo User's Guide. ## License Copyright (C) 2010-2019 The ESPResSo project -Copyright (C) 2002,2003,2004,2005,2006,2007,2008,2009,2010 -Max-Planck-Institute for Polymer Research, Theory Group - + +Copyright (C) 2002-2010 Max-Planck-Institute for Polymer Research, Theory Group + This file is part of ESPResSo. - + ESPResSo is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. - + ESPResSo is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - + You should have received a copy of the GNU General Public License along with this program. If not, see . From e28cf228efe5fc92970e025ea6ffe66a568ad76a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sat, 30 May 2020 21:46:38 +0200 Subject: [PATCH 3/8] docs: Add links to documentation resources --- Readme.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/Readme.md b/Readme.md index 928ef2415b5..2258bdb3dba 100644 --- a/Readme.md +++ b/Readme.md @@ -47,16 +47,14 @@ simulations. It is mainly developed at the Institute for Computational Physics of the University of Stuttgart, but has contributors from all over the world. - ## Documentation -You can find documentation on how to compile, use and develop ESPResSo -on the homepage at [http://espressomd.org/html/doc/index.html](http://espressomd.org/html/doc/index.html). - -ESPResSo is intended to be used by people that have proper knowledge -of simulation techniques and know how to use them. We do not take -responsibility if you use ESPResSo to create and publish bogus -results. You have been warned! +The [user guide](http://espressomd.org/html/doc/index.html) will +walk you through the basic usage of ESPResSo. Advanced simulation +methods are extensively documented, with examples and links to the +relevant literature. Additional resources can be found on the +homepage at http://espressomd.org/wordpress/documentation/, such +as tutorials and doxygen documentation. ## PLEASE CITE US! From 2735815be3c798ee72d918982084532bf259c18d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sun, 31 May 2020 16:49:02 +0200 Subject: [PATCH 4/8] docs: Explain how to get ESPResSo releases --- Readme.md | 11 +++++++++++ doc/sphinx/introduction.rst | 30 ++++++++++++++++++++++++++---- 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/Readme.md b/Readme.md index 2258bdb3dba..c77c55313a8 100644 --- a/Readme.md +++ b/Readme.md @@ -56,6 +56,17 @@ relevant literature. Additional resources can be found on the homepage at http://espressomd.org/wordpress/documentation/, such as tutorials and doxygen documentation. +## Installation + +Detailed installation instructions for Ubuntu and macOS can be found in the +documentation, section [Installation](http://espressomd.org/html/doc/installation.html). + +For most users, we recommend downloading the latest release version of ESPResSo. You +can find it in the [release page](https://github.com/espressomd/espresso/releases), +together with past releases until 4.0. When choosing a release, we recommend that +you get the latest bugfix release in that line. For example, for 4.1 you would like +to use 4.1.2. + ## PLEASE CITE US! If you use ESPResSo and obtain scientific results that you publish, we diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index 2f6088440fc..e5408a92a73 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -522,13 +522,35 @@ report so to the developers. +.. _Software releases: + +Software releases +----------------- + +|es| releases use the following versioning scheme: ``major.minor.patch_level``. +New features are introduced in major and minor releases, while bugfix releases +only patch bugs without adding or removing features. Since the ``patch_level`` +doesn't affect the capabilities of the software, it's common to refer to +releases simply as ``major.minor``. + +New users should always choose the latest release. When opting for an +older release, we recommend using the latest bugfix release from that +line (for example 4.0.2 instead of 4.0), unless you need to capture the +behavior of bugs for reproducibility reasons. When filing bug reports +or citing |es|, the version should always be mentioned. + +Releases from 4.0 onwards can be found on +`GitHub `_. +Older releases from 2.1 to 3.3 can be found in +`GNU Savannah `_. +See our policy on :ref:`API backward compatibility +` +if you need more details. + .. _Intended interface compatibility between ESPResSo versions: Intended interface compatibility between |es| versions ------------------------------------------------------- - -We use the following versioning scheme: -major.minor.patch_level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ With regards to the stability of the Python interface, we have the following guidelines: From 2d71cd1fff358160ea3b0d073eea7272f814cf16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sun, 31 May 2020 18:09:51 +0200 Subject: [PATCH 5/8] docs: Explain release workflow and mailing list Invite users to join the community by subscribing to the mailing list to keep up-to-date with releases and give feedback in surveys. For new contributors, give a simplified overview of the release workflow and explain how to find the live release notes. --- Readme.md | 8 ++++++++ doc/sphinx/contributing.rst | 2 +- doc/sphinx/introduction.rst | 29 +++++++++++++++++++++++++++-- 3 files changed, 36 insertions(+), 3 deletions(-) diff --git a/Readme.md b/Readme.md index c77c55313a8..81d9964c154 100644 --- a/Readme.md +++ b/Readme.md @@ -77,6 +77,14 @@ A number of algorithms in ESPResSo are fairly advanced and unique to ESPResSo. The authors of these contributions kindly ask you to cite the relevant publications, as indicated in the ESPResSo User's Guide. +### Join the community + +Please consider subscribing to our +[mailing list](http://espressomd.org/wordpress/community-and-support/mailing-lists/) +if you're actively using ESPResSo, as we occasionally need community +feedback when making decisions on the future of specific features in +upcoming releases. You'll also get notifications on bugfix releases. + ## License Copyright (C) 2010-2019 The ESPResSo project diff --git a/doc/sphinx/contributing.rst b/doc/sphinx/contributing.rst index f5f9b9c4ca8..f889df7b86b 100644 --- a/doc/sphinx/contributing.rst +++ b/doc/sphinx/contributing.rst @@ -9,7 +9,7 @@ time, we will not describe its contents in detail but rather request the reader to go directly to the URL. Among other things, one can find information about the following topics there: -- Latest stable release of and older releases +- Latest stable release of |es| and older releases - Obtaining development version of |es| diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index e5408a92a73..53f4d7c919c 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -417,7 +417,7 @@ use. We distinguish between five levels: In the "Tested" column, we note whether there is an integration test for the method. If you believe that the status of a certain method is wrong, please -report so to the developers. +report so to the developers using the instructions in :ref:`Contributing`. .. tabularcolumns:: |l|c|c|c| @@ -537,7 +537,8 @@ New users should always choose the latest release. When opting for an older release, we recommend using the latest bugfix release from that line (for example 4.0.2 instead of 4.0), unless you need to capture the behavior of bugs for reproducibility reasons. When filing bug reports -or citing |es|, the version should always be mentioned. +or citing |es|, the version should always be mentioned. See +our policy on :ref:`bug reports ` for more details. Releases from 4.0 onwards can be found on `GitHub `_. @@ -547,6 +548,30 @@ See our policy on :ref:`API backward compatibility ` if you need more details. +.. _Release workflow: + +Release workflow +^^^^^^^^^^^^^^^^ + +Major and minor releases are branched from the development branch ``python``. +When a version ``X.Y.0`` is released, the ``python`` branch is copied +to a new branch named ``X.Y``, at which point the ``python`` branch is ready +to accept contributions for the ``X.Y+1.0`` release. The ``X.Y`` branch +still gets bugfix releases ``X.Y.1``, ``X.Y.2``, ..., for several months. + +`GitHub milestones `_ +track the progress of each release. They can give you an idea of the changes +in future releases, although it's more convenient to follow the live release +notes in the `wiki `_ (listed +under "Planned releases" in the side bar). These notes are updated monthly. +Most users will only be interested in the live release notes of the +planned bugfix release for the version of |es| they're using. + +If you're actively developing code for |es|, you might also be interested in +the summaries of the `ESPResSo meetings +`_, +where the core team discusses plans for future releases and feature freezes. + .. _Intended interface compatibility between ESPResSo versions: Intended interface compatibility between |es| versions From f8ec2dd21a672fdbe2eb22d6cf71b19e1dc98060 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Sun, 31 May 2020 18:41:37 +0200 Subject: [PATCH 6/8] docs: Show how to cite ESPResSo and its algorithms --- Readme.md | 18 +++++++------- doc/sphinx/introduction.rst | 48 ++++++++++++++++++++++++++++++++++++- doc/sphinx/zrefs.bib | 11 +++++++++ 3 files changed, 67 insertions(+), 10 deletions(-) diff --git a/Readme.md b/Readme.md index 81d9964c154..acf620ee132 100644 --- a/Readme.md +++ b/Readme.md @@ -67,15 +67,15 @@ together with past releases until 4.0. When choosing a release, we recommend tha you get the latest bugfix release in that line. For example, for 4.1 you would like to use 4.1.2. -## PLEASE CITE US! - -If you use ESPResSo and obtain scientific results that you publish, we -would ask you to acknowledge the usage of ESPResSo by citing the relevant papers: -http://espressomd.org/wordpress/about/please-cite-us/ - -A number of algorithms in ESPResSo are fairly advanced and unique to -ESPResSo. The authors of these contributions kindly ask you to cite the -relevant publications, as indicated in the ESPResSo User's Guide. +### Please cite us! + +If you use ESPResSo to publish scientific results, we would ask you to +acknowledge this usage by mentioning the software with its version number and +[citing the relevant papers](http://espressomd.org/wordpress/about/please-cite-us/). +A number of algorithms in ESPResSo are fairly advanced and unique to ESPResSo. +The authors of these contributions kindly ask you to cite the relevant +publications, as indicated in the documentation. For detailed instructions, see +[How to cite ESPResSo](http://espressomd.org/html/doc/introduction.html#how-to-cite-espresso). ### Join the community diff --git a/doc/sphinx/introduction.rst b/doc/sphinx/introduction.rst index 53f4d7c919c..3285fc99b95 100644 --- a/doc/sphinx/introduction.rst +++ b/doc/sphinx/introduction.rst @@ -538,7 +538,8 @@ older release, we recommend using the latest bugfix release from that line (for example 4.0.2 instead of 4.0), unless you need to capture the behavior of bugs for reproducibility reasons. When filing bug reports or citing |es|, the version should always be mentioned. See -our policy on :ref:`bug reports ` for more details. +our policies on :ref:`bug reports ` and +:ref:`citing the software ` for more details. Releases from 4.0 onwards can be found on `GitHub `_. @@ -597,4 +598,49 @@ guidelines: * No guarantees are made with respect to the C++ bindings in the simulation core. +.. _How to cite ESPResSo: + +How to cite |es| +^^^^^^^^^^^^^^^^ + +Please cite :cite:`weik19a` (BibTeX key ``weik19a`` in :file:`doc/sphinx/zrefs.bib`) +for |es| 4.0 and later, or :cite:`arnold13a` and :cite:`limbach06a` +(BibTeX keys ``arnold13a`` and ``limbach06a`` in :file:`doc/sphinx/zrefs.bib`) +for |es| 2.0 to 3.3. To find the version number, use the following command: + +.. code-block:: bash + + ./pypresso -c "import espressomd.version;print(espressomd.version.friendly())" + +A number of algorithms in |es| are fairly advanced and unique to |es|. +The authors of these contributions kindly ask you to cite the relevant +publications, using the BibTeX entries indicated in this user guide. + +A complete citation would look like this: + + Simulations were carried out with ESPResSo 4.1[24] using the ICC\* + algorithm[25]. + + | [24] F. Weik, R. Weeber, K. Szuttor *et al.* ESPResSo 4.0 -- an + extensible software package for simulating soft matter systems. + *Eur. Phys. J. Spec. Top.* **227**, 1789--1816 (2019). + doi:\ `10.1140/epjst/e2019-800186-9 `_. + | [25] C. Tyagi, M. Süzen, M. Sega *et al.* An iterative, fast, + linear-scaling method for computing induced charges on arbitrary + dielectric boundaries. *J. Chem. Phys.* **132**, 154112 (2010). + doi:\ `10.1063/1.3376011 `_. + +You may also provide the patch level, when relevant. If you developed code +for |es| and made it available in a publicly accessible repository, you +should consider providing the corresponding URL, for example in a footnote: + + The method was implemented for ESPResSo 4.1.2[24]. The full code is + available online\*. + + | \* https://github.com/username/espresso/tree/implemented-algorithm + + | [24] F. Weik, R. Weeber, K. Szuttor *et al.* ESPResSo 4.0 -- an + extensible software package for simulating soft matter systems. + *Eur. Phys. J. Spec. Top.* **227**, 1789--1816 (2019). + doi:\ `10.1140/epjst/e2019-800186-9 `_. diff --git a/doc/sphinx/zrefs.bib b/doc/sphinx/zrefs.bib index 1b72dfeb10f..741a23fe137 100644 --- a/doc/sphinx/zrefs.bib +++ b/doc/sphinx/zrefs.bib @@ -1065,6 +1065,17 @@ @Article{hofling11a owner = {rajarshi} } +@Article{weik19a, + author = {Weik, Florian and Weeber, Rudolf and Szuttor, Kai and Breitsprecher, Konrad and de Graaf, Joost and Kuron, Michael and Landsgesell, Jonas and Menke, Henri and Sean, David and Holm, Christian}, + title = {{ESPResSo} 4.0 -- An Extensible Software Package for Simulating Soft Matter Systems}, + journal = {The European Physical Journal Special Topics}, + year = {2019}, + volume = {227}, + number = {14}, + pages = {1789--1816}, + doi = {10.1140/epjst/e2019-800186-9}, +} + @article{yaghoubi2015a, title={New modified weight function for the dissipative force in the DPD method to increase the Schmidt number}, author={Yaghoubi, S and Shirani, E and Pishevar, AR and Afshar, Yaser}, From 06e19da5298465b59ca5d9ed9ddce86e6c4f26ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 5 Jun 2020 10:59:56 +0200 Subject: [PATCH 7/8] docs: Shorten license section --- Readme.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/Readme.md b/Readme.md index acf620ee132..349363baa50 100644 --- a/Readme.md +++ b/Readme.md @@ -91,18 +91,10 @@ Copyright (C) 2010-2019 The ESPResSo project Copyright (C) 2002-2010 Max-Planck-Institute for Polymer Research, Theory Group -This file is part of ESPResSo. - ESPResSo is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. -ESPResSo is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . - +You should have received a [copy](COPYING) of the GNU General Public License +along with this program. If not, see . From 23a1e2509d7ac5b874941fed4a557745b29b56d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 5 Jun 2020 11:00:47 +0200 Subject: [PATCH 8/8] docs: Move mailing list up --- Readme.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/Readme.md b/Readme.md index 349363baa50..276c42d8d36 100644 --- a/Readme.md +++ b/Readme.md @@ -67,6 +67,14 @@ together with past releases until 4.0. When choosing a release, we recommend tha you get the latest bugfix release in that line. For example, for 4.1 you would like to use 4.1.2. +### Join the community + +Please consider subscribing to our +[mailing list](http://espressomd.org/wordpress/community-and-support/mailing-lists/) +if you're actively using ESPResSo, as we occasionally need community +feedback when making decisions on the future of specific features in +upcoming releases. You'll also get notifications on bugfix releases. + ### Please cite us! If you use ESPResSo to publish scientific results, we would ask you to @@ -77,14 +85,6 @@ The authors of these contributions kindly ask you to cite the relevant publications, as indicated in the documentation. For detailed instructions, see [How to cite ESPResSo](http://espressomd.org/html/doc/introduction.html#how-to-cite-espresso). -### Join the community - -Please consider subscribing to our -[mailing list](http://espressomd.org/wordpress/community-and-support/mailing-lists/) -if you're actively using ESPResSo, as we occasionally need community -feedback when making decisions on the future of specific features in -upcoming releases. You'll also get notifications on bugfix releases. - ## License Copyright (C) 2010-2019 The ESPResSo project