Expand the contributing guide.

Author: domdfcoding

doc-source/Source.rst

@@ -8,9 +8,10 @@ The recommended way to build from source is via tox_:
 
 	tox -e build
 
-As well as build the sdist and wheel it will check them for common errors, such as missing files or potential rendering issues on PyPI_.
+As well as building the sdist and wheel this will check them for common errors,
+such as missing files or potential rendering issues on PyPI_.
 
-The output files will be in the directory ``dist``.
+The output files will be in the ``dist`` directory.
 
 If you wish, you may also use `pep517.build`_ or another :pep:`517`-compatible build tool.
 

doc-source/building.rst

@@ -7,10 +7,13 @@ Most projects have documentation generated with Sphinx_ and hosted on ReadTheDoc
 .. _Sphinx: https://www.sphinx-doc.org/en/master/
 .. _ReadTheDocs: https://readthedocs.org/
 
+The documentation source is located in the ``doc-source`` directory.
 A local copy of the documentation can be built with ``tox``:
 
 .. prompt:: bash
 
 	tox -e docs
 
-.. TODO:: repo-helper pycharm docs?
+The built documentation can be found in the ``doc-soure/build/html`` directory.
+
+.. TODO:: changing the documentation configuration

doc-source/documentation.rst

@@ -21,3 +21,4 @@ contributing
 	tests
 	documentation
 	building
+	release-process

doc-source/github-actions-checks.png

@@ -0,0 +1,54 @@
+================
+Release Process
+================
+
+New releases are created using a combination of `repo-helper`_ and `GitHub Actions`_.
+To start you will need ``repo-helper`` installed:
+
+.. prompt:: bash
+
+	python3 -m pip install repo-helper --upgrade
+
+Then ensure all changes have been committed_ or stashed_:
+
+.. prompt:: bash
+
+	git status
+
+.. parsed-literal::
+
+	On branch master
+	Your branch is up-to-date with 'origin/master'.
+
+	nothing to commit, working tree clean
+
+
+The create a release using `repo-helper release`_:
+
+.. prompt:: bash
+
+	repo-helper release minor
+
+Repleace ``minor`` with ``major`` or ``patch`` as appropriate.
+
+Once the release has been created locally, push to GitHub. Ensure you push the tag too:
+
+.. prompt:: bash
+
+	git push --tags
+
+Once the tests pass GitHub Actions will take care of building and uploading to PyPI_
+and Anaconda_ (if enabled for the project).
+You should keep an eye on the tests to ensure they pass.
+
+The release will be automatcally copied to `GitHub Releases`_ within the next two days using OctoCheese_
+
+.. _repo-helper: https://docs.repo-helper.uk
+.. _GitHub Actions: https://github.com/features/actions
+.. _committed: https://git-scm.com/docs/git-commit
+.. _stashed: https://git-scm.com/docs/git-stash
+.. _repo-helper release: https://docs.repo-helper.uk/en/latest/usage/release.html
+.. _PyPI: https://pypi.org/
+.. _Anaconda: https://anaconda.org/domdfcoding/repo
+.. _GitHub Releases: https://docs.github.com/en/github/administering-a-repository/about-releases
+.. _OctoCheese: https://octocheese.readthedocs.io/en/latest/

doc-source/index.rst

@@ -61,3 +61,56 @@ Coverage
 
 .. TODO:: this section
 .. TODO:: coverage measurements in pull requests
+
+On POSIX systems with Firefox_ installed an HTML coverage report can be generated by running:
+
+.. prompt:: bash
+
+	tox -n cov
+
+Ensure your changes do not cause a significant decrease in the test coverage.
+If the coverage drops below the level set in ``repo_helper.yml`` (or 80% not specified) the tests will fail.
+
+.. _Firefox: https://www.mozilla.org/en-GB/firefox/
+
+GitHub Actions
+-----------------
+
+Tests are run on pushes to GitHub using `GitHub Actions`_.
+You can see the results of these test at the bottom of the pull request page:
+
+.. figure:: github-actions-checks.png
+
+A label will be added to the pull request automatically if the tests fail:
+
+.. figure:: pull-request-labels
+
+This makes it easy to identify which tests are failing.
+Once the tests pass the label will be removed automatically.
+
+If you are a first time contributor to a project manual approval is required for GitHub Actions to run.
+For more information see https://github.blog/2021-04-22-github-actions-update-helping-maintainers-combat-bad-actors/
+
+`Branch protection`_ is used to ensure the following tests pass before merging pull requests:
+
+* Tests on Windows and Linux for all CPython version between 3.6 and 3.9 supported by the project.
+* Tests on Windows and Linux for PyPy 3.6, if supported by the project.
+* mypy type checking on Windows and Linux.
+* Flake8
+* The documentation check, if the project has documentation.
+
+If the project only supports Linux the tests on Window will not run and are not required to merge the pull request.
+
+Tests on macOS are optional as they take longer than other platforms.
+CPython 3.10 and PyPy 3.7 are considered experimental and will not block a pull request from being merged if they fail.
+However, you should still check the results of these runs to ensure your changes have not introduced any errors there.
+
+You should check the :guilabel:`Files changed` tab of the pull request to see whether any issues have been identified.
+This can be due to syntax errors in the documentation source or issues identified by flake8 and Codefactor_.
+
+Your pull request may be commented on by Coveralls_ to report any changes to the code coverage.
+
+.. _GitHub Actions: https://github.com/features/actions
+.. _Branch protection: https://docs.github.com/en/github/administering-a-repository/about-protected-branches
+.. _Codefactor: https://www.codefactor.io/
+.. _Coveralls: https://coveralls.io/

doc-source/pull-request-labels.png

@@ -31,3 +31,4 @@ extra_sphinx_extensions:
 
 exclude_files:
  - contributing
+ - Source_rst