pyeve · funkyfuture · Aug 9, 2023 · Aug 4, 2023
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -1,39 +1,9 @@
 <!--
-This issue tracker is dedicated to bugs and feature requests.
+This issue tracker is dedicated to bugs only.
 
 **IT IS NOT SUPPOSED FOR ANY USAGE RELATED QUESTIONS.**
 (sorry for that loud but necessary statement.)
 
-Stack Overflow is the go-to place for general questions and general how-tos. On
-SO, questions tagged with the 'cerberus' tag are actively monitored by the
-project author, contributors and users. If consultancy there leads you to the
-conclusion that the documentation should be improved, it is a valid bug report
-here.
-
-When reporting a bug, please post a full code example and make it as simple as
-possible. From your use-case throw everything out that is irrelevant to evoke
-the bug.
-
-**It is mandatory to provide the information in the template below:**
-
+Stack Overflow is the go-to place for general questions and general how-tos.
+https://stackoverflow.com/questions/tagged/cerberus
 -->
-
-Used Cerberus version / latest commit: …
-
-- [ ] I have the capacity to improve the docs when my problem is solved.
-- [ ] I have the capacity to submit a patch when a bug is identified.
-
-- [ ] My question does not concern a practical use-case that I can't figure out
- to solve.
-
-----
-
-#### Use-case abstract
-
-<!-- please summarize your use-case -->
-
-----
-
-#### Bug report / Feature request
-
-<!-- describe your issue here -->
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
diff --git a/docs/contribute.rst b/docs/contribute.rst
@@ -1,4 +1,35 @@
-.. include:: ../CONTRIBUTING.rst
+How to Contribute
+=================
+
+There are no plans to develop Cerberus further than the current feature set.
+Bug fixes and documentation improvements are welcome and will be published with
+yearly service releases.
+
+
+Making Changes
+--------------
+* Fork_ the repository_ on GitHub.
+* Create a new topic branch from the ``1.3.x`` branch.
+* Make commits of logical units (if needed rebase your feature branch before
+ submitting it).
+* Make sure your commit messages are in the `proper format`_.
+* If your commit fixes an open issue, reference it in the commit message.
+* Make sure you have added the necessary tests for your changes.
+* Run all the tests to assure nothing else was accidentally broken.
+* Install and enable pre-commit_ (``pip install pre-commit``, then ``pre-commit
+ install``) to ensure styleguides and codechecks are followed.
+* Don't forget to add yourself to the ``AUTHORS.rst`` document.
+
+These guidelines also apply when helping with documentation (actually, for
+typos and minor additions you might choose to `fork and edit`_).
+
+
+Submitting Changes
+------------------
+* Push your changes to the topic branch in your fork of the repository.
+* Submit a `Pull Request`_.
+* Wait for maintainer feedback. Please be patient.
+
 
 Running the Tests
 -----------------
@@ -10,6 +41,7 @@ with pytest_:
 
  $ pytest cerberus/tests
 
+
 Testing with other Python versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -26,16 +58,17 @@ that the interpreters themselves need to be available on the system.
 This might take some time the first run as the different virtual environments
 are created and dependencies are installed.
 
-If something goes **wrong** and one test fails, you might need to run that test
-in the specific python version. You can use the created environments to run
-some specific tests. For example, if a test suite fails in Python 3.11:
+If something goes wrong and one test fails, you might need to run that test in
+the specific python version. You can use the created environments to run some
+specific tests. For example, if a test suite fails in Python 3.11:
 
 .. code-block:: console
 
  $ tox -e py311
 
 Have a look at ``tox.ini`` for the available test environments and their setup.
 
+
 Running the benchmarks
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -46,6 +79,7 @@ Cerberus' performance:
 
  $ pytest cerberus/benchmarks
 
+
 Building the HTML-documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -64,10 +98,12 @@ The HTML build is triggered with:
 
 The result can be accessed by opening ``docs/_build/html/index.html``.
 
-Source Code
------------
-
-Source code is available at `GitHub <https://github.com/pyeve/cerberus>`_.
 
+.. _Fork: https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo
+.. _`fork and edit`: https://github.blog/2011-04-26-forking-with-the-edit-button/
+.. _pre-commit: https://pre-commit.com/
+.. _`proper format`: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+.. _`Pull Request`: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request
 .. _pytest: https://pytest.org
+.. _repository: https://github.com/pyeve/cerberus
 .. _tox: https://tox.readthedocs.io
diff --git a/docs/install.rst b/docs/install.rst
@@ -2,7 +2,10 @@ Cerberus Installation
 =====================
 
 This part of the documentation covers the installation of Cerberus. The first
-step to using any software package is getting it properly installed.
+step to using any software package is getting it properly installed. Please
+refer to one of the many established ways to work in project-specific virtual
+environments, i.e. the `Virtual Environments and Packages`_ section of the
+Pyton documentation.
 
 
 Stable Version
@@ -18,46 +21,16 @@ Cerberus is on the PyPI_ so all you need to do is:
 Development Version
 -------------------
 
-Cerberus is actively developed in a `GitHub Repository`_ where the code. If you
-want to work with the development version, there are two ways: You can either
-let ``pip`` pull in the development version, or you can tell it to operate on a
-``git`` checkout. Either way, virtualenv is recommended.
-
-Get the git checkout in a new virtualenv and run in development mode.
+Obtain the source (either as source distribution from the PyPI, with ``git`` or
+other means that the Github platform provides) and use the following command
+in the source's root directory for an editable installation. Subsequent changes
+to the source code will affect its following execution without re-installation.
 
 .. code-block:: console
 
- $ git clone [email protected]:pyeve/cerberus.git
- Initialized empty Git repository in ~/dev/cerberus.git/
- $ cd cerberus
- $ virtualenv venv --distribute
- New python executable in venv/bin/python
- Installing distribute............done.
- $ . venv/bin/activate
  $ pip install -e .
- ...
- Finished processing dependencies for Cerberus
-
-This will pull in the dependencies and activate the git head as the current
-version inside the virtualenv. Then all you have to do is run ``git pull
-origin`` to update to the latest version.
-
-To just get the development version without git, do this instead:
-
-.. code-block:: console
-
- $ mkdir cerberus
- $ cd cerberus
- $ virtualenv venv --distribute
- $ . venv/bin/activate
- New python executable in venv/bin/python
- Installing distribute............done.
- $ pip install git+git://github.com/pyeve/cerberus.git
- ...
- Cleaning up...
-
-And you're done!
 
 
 .. _GitHub Repository: https://github.com/pyeve/cerberus
 .. _PyPI: https://pypi.org/project/Cerberus
+.. _Virtual Environments and Packages: https://docs.python.org/3/tutorial/venv.html