From 24732645c84c8123c08a8aec1daf26ec2cc4ce35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 15 Apr 2022 20:30:51 +0200 Subject: [PATCH] doc: Rewrite Contributing and Community pages Split the Contributing chapter to create a Community chapter. Document the Summer School and how to access the teaching material. Update the Contributing page of the project community standards. --- CONTRIBUTING.md | 42 +++++++++++++++--------------- doc/sphinx/CMakeLists.txt | 1 + doc/sphinx/community.rst | 51 +++++++++++++++++++++++++++++++++++++ doc/sphinx/contributing.rst | 33 ------------------------ doc/sphinx/index.rst | 8 ++++-- 5 files changed, 80 insertions(+), 55 deletions(-) create mode 100644 doc/sphinx/community.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f72fabba9..31b658ce90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,27 +3,26 @@ Thank you for your interest in contributing to ESPResSo! There are many ways to contribute and we appreciate all of them. This -document is a quite lengthy, so here is a list of links to the +document is quite lengthy, so here is a list of links to the major sections: * [New Features](#new-features) * [Bug Reports](#bug-reports) * [Pull Requests](#pull-requests) * [Writing Documentation](#writing-documentation) -* [Helpful Links and Information](#helpful-links-and-information) -If you have questions, please make a post on [the developers +If you have questions, please make a post on [the users mailing list][mailing-list]. -[mailing-list]: https://lists.nongnu.org/mailman/listinfo/espressomd-devel +[mailing-list]: https://lists.nongnu.org/mailman/listinfo/espressomd-users ## New Features [new-features]: #new-features If you plan to create a new feature for ESPResSo, it is -*absolutely essential* that you first post your plan on [the -developers mailing list][mailing-list]. This way we can give you -useful tips how to go about a successful integration and can +*absolutely essential* that you first post your plan on the +[users mailing list][mailing-list]. This way we can give you +useful tips on how to go about a successful integration and can point out possibly reusable code. Maybe your feature even exists already and you just didn't notice it, so we want to save you the effort. @@ -31,33 +30,35 @@ effort. ## Bug Reports [bug-reports]: #bug-reports -We cannot fix bugs we don't know about, so please report -liberally. If you are unsure whether something is a bug or not, -feel free to file a bug anyway. +We cannot fix bugs we don't know about, so please report liberally. +If you are unsure whether something is a bug or not, feel free to +ask on the [users mailing list][mailing-list] or on the +[discussion forum](https://github.com/espressomd/espresso/discussions). To fix your problem quickly it is essential that we have an easy way to reproduce your bug. Therefore you should include in your report the *desired behavior*, a *specific problem or error* and -*the shortest script necessary* to reproduce it. Ideally you -also include the affected version and list of features activated -in `myconfig.hpp`. +*the shortest script necessary* to reproduce it. We have handy +step-by-step instructions in the wiki page [Filing bug reports +](https://github.com/espressomd/espresso/wiki/Filing-bug-reports). ## Pull Requests [pull-requests]: #pull-requests -Pull requests are the primary mechanism we use to change -ESPResSo. GitHub itself has some [great documentation][pull-requests] +Pull requests are the primary mechanism we use to change ESPResSo. +GitHub itself has some [great documentation][gh-pull-requests] on using the Pull Request feature. We use the "fork and pull" -model [described here][development-models], where contributors +model [described here][gh-development-models], where contributors push changes to their personal fork and create pull requests to bring those changes into the source repository. -[pull-requests]: https://help.github.com/articles/about-pull-requests/ -[development-models]: https://help.github.com/articles/about-collaborative-development-models/ +[gh-pull-requests]: https://help.github.com/articles/about-pull-requests/ +[gh-development-models]: https://help.github.com/articles/about-collaborative-development-models/ Please make pull requests against the `python` branch. -We have a continuous integration system for automated testing, +We have a continuous integration system for [automated testing]( +https://github.com/espressomd/espresso/wiki/Code-review#automated-code-review), which runs on all pull requests to see whether new additions play nicely with the existing code. Because it takes a long time for all the tests to be completed, you might want to run `make check` @@ -65,7 +66,8 @@ with the settings from `maintainer/configs/maxset.hpp` locally first. All pull requests are reviewed by one or more of the ESPResSo -core team members. +core team members, as explained in the wiki page [Code review +](https://github.com/espressomd/espresso/wiki/Code-review#Human_code_review). ## Writing Documentation [writing-documentation]: #writing-documentation diff --git a/doc/sphinx/CMakeLists.txt b/doc/sphinx/CMakeLists.txt index 9d4e3d832f..8d5fe1ed69 100644 --- a/doc/sphinx/CMakeLists.txt +++ b/doc/sphinx/CMakeLists.txt @@ -29,6 +29,7 @@ if(SPHINX_FOUND) "${CMAKE_CURRENT_SOURCE_DIR}/advanced_methods.rst" "${CMAKE_CURRENT_SOURCE_DIR}/analysis.rst" "${CMAKE_CURRENT_SOURCE_DIR}/appendix.rst" + "${CMAKE_CURRENT_SOURCE_DIR}/community.rst" "${CMAKE_CURRENT_SOURCE_DIR}/constraints.rst" "${CMAKE_CURRENT_SOURCE_DIR}/contributing.rst" "${CMAKE_CURRENT_SOURCE_DIR}/ek.rst" diff --git a/doc/sphinx/community.rst b/doc/sphinx/community.rst new file mode 100644 index 0000000000..de3a395c38 --- /dev/null +++ b/doc/sphinx/community.rst @@ -0,0 +1,51 @@ +.. _Community: + +Community +========= + +.. _Community support: + +Community support +----------------- + +If you have any questions concerning |es| which you cannot resolve by +yourself, you may search for an answer on: + +- `GitHub issue tracker `__ +- `GitHub discussions `__ +- `espressomd-users mailing list archive `__ +- `Installation FAQ `__ + +If you still didn't find a solution, you may consider either opening a new +issue or discussion on GitHub, or sending an email on the mailing list. +Instructions on how to register to the mailing lists and post messages can be +found in `Mailing Lists +`__. +It is recommended to use these communication channels rather than to contact +individual developers, for several reasons: + +- All users get your message and you have a higher + probability that it is answered soon. +- Your question and the answers are archived and the archives can be + searched by others. +- The answer may be useful also to other users. +- There may not be a unique answer to your problem and it may be useful + to get suggestions from different people. + +Please remember that this is a community mailing list and a community GitHub +forum. It is other users and developers who are answering your questions. +They do it in their free time and are not paid for doing it. + +.. _Summer Schools: + +Summer Schools +-------------- + +Every year in October, a 5-day workshop is organized at University of Stuttgart, Germany. +Registration is free of charge and is managed by `CECAM `__. +Past events are archived on the |es| official website, under `Summer Schools +`__. +The teaching material can be found in the online documentation, section +`Tutorials `__. The lectures +can be found on the `ESPResSo Simulation Package +`__ YouTube channel. diff --git a/doc/sphinx/contributing.rst b/doc/sphinx/contributing.rst index 86bdb655a2..b4a124265d 100644 --- a/doc/sphinx/contributing.rst +++ b/doc/sphinx/contributing.rst @@ -17,39 +17,6 @@ The official website at https://espressomd.org provides additional information: - Archives of both developers' and users' mailing lists - Registering to mailing lists -.. _Community support: - -Community support ------------------ - -If you have any questions concerning |es| which you cannot resolve by -yourself, you may search for an answer on: - -- `GitHub issue tracker `__ -- `GitHub discussions `__ -- `espressomd-users mailing list archive `__ -- `Installation FAQ `__ - -If you still didn't find a solution, you may consider either opening a new issue -on GitHub or sending an email on the mailing list. Instructions on how to -register to the mailing lists and post messages can be found in `Mailing Lists -`__. - -For several reasons it is recommended to send all questions to the issue -tracker or mailing list rather than to contact individual developers: - -- All registered users get your message and you have a higher - probability that it is answered soon. -- Your question and the answers are archived and the archives can be - searched by others. -- The answer may be useful also to other registered users. -- There may not be a unique answer to your problem and it may be useful - to get suggestions from different people. - -Please remember that this is a community mailing list and a community issue -tracker. It is other users and developers who are answering your questions. -They do it in their free time and are not paid for doing it. - .. _Contributing your own code: Contributing your own code diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 7d85cf1176..39dd13cf55 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -30,6 +30,7 @@ User's Guide advanced_methods.rst reaction_methods.rst under_the_hood.rst + community.rst contributing.rst appendix.rst bibliography.rst @@ -39,8 +40,11 @@ User's Guide Online resources ---------------- -* `Repository `_ -* `Wiki `_ +* `GitHub repository `_ +* `GitHub discussions `_ +* `ESPResSo wiki `_ +* `Online documentation `_ +* `Official website `_ Python modules --------------