Modifying contribution documentation for new workflow

docs/source/dev/testing.rst

@@ -51,8 +51,11 @@ collaborative features and robust version control. Nevertheless, key principles
 of the process are considered to be the automatic build and automatic testing
 of the code which need to be performed each time the master code is adjourned.
 
+.. _runtesting:
+
 Testing in JADE
 ---------------
+
 Unit testing in JADE is defined and run with the help of the ``pytest`` module
 while the code test coverage is monitored through the ``coverage`` one.
 

docs/source/dev/workflow.rst

@@ -19,7 +19,7 @@ Terminology
 There are different ways to contribute to JADE, and not all of them require you to code:
 
 * A *Tester* is a JADE frequent user that helps the project giving detailed feedback on JADE stable and
-  beta releases. This can also come in the form of openining issues.
+  beta releases. This can also come in the form of opening issues.
 * An *Expert* is a senior figure that provides knowledge in the field of nuclear data, Monte Carlo codes,
   and benchmarks, helping steering JADE priorities
 * A *Contributor* is any individual creating or commenting on an issue or pull request.
@@ -45,34 +45,55 @@ Branching model
     :width: 600
     :align: center
 
-    Branching model showing Devlop, Feature, Benchmark, Release and Hotfix branches
+    Branching model showing Developing, Feature, Benchmark, Release and Hotfix branches
 
-Development of JADE relies heavily on branching; specifically, we use a branching model
-sometimes referred to as git flow. If you plan to contribute to JADE development,
-we highly recommend that you read this
+Development of JADE relies heavily on branching; specifically, we use a modified 
+version of the branching model sometimes referred to as git flow. If you plan to 
+contribute to JADE development, we highly recommend that you read this
 `blog post <https://nvie.com/posts/a-successful-git-branching-model/>`_
-to get a sense of how the branching
-model works. There are two main branches that always exist: ``master`` and ``Developing``.
-The master branch is a stable branch that contains the latest release of the code.
-The develop branch is where any ongoing development takes place prior to a release and is
-not guaranteed to be stable. When the project leader decides that a release should occur,
-the ``Developing`` branch is merged into master.
-
-All new features, enhancements, and bug fixes should be developed on a branch that branches off
-of Developing. When the feature is completed, a pull request is initiated on GitHub that is
-then reviewed by an approver. If the pull request is satisfactory, it is then merged into develop.
-Note that a committer may not review their own pull request
-(i.e., an independent code review is required).
+to get a sense of how the branching model works. 
+
+There are two main branches that always exist: ``master`` and ``Developing``. 
+The ``master`` branch is a stable branch that contains the latest release of the 
+code. The ``Developing`` branch is where any ongoing development takes place 
+prior to a release and is not guaranteed to be stable. 
+
+Other branches will be created as required for different purposes which are 
+listed below. When any of these branches need to be merged (e.g., into the 
+``Developing`` branch), a pull request (PR) should be initiated on GitHub that is 
+then reviewed by an approver (see `Requirements for a successful merge`_). If the 
+pull request is satisfactory, it is then merged into develop. Note that a 
+committer may not review their own pull request (i.e., an independent code 
+review is required). 
+
+* **Feature** - All new features, enhancements, and bug fixes should be 
+  developed on a ``Feature`` branch off ``Developing``. Most branches on the 
+  repository will be of this type and consist of work by the core JADE team.
+* **Benchmark** - This type of branch is similar to that above, except it is 
+  specifically for adding new benchmarks. This type of branch will be the most 
+  frequently Pull Requested (PR'd) from forks outside the core team.
+* **Release** - This type of branch will come off ``Developing`` when  the project 
+  leader decides that a release should occur. This is solely for allowing further 
+  testing and bug fixes for an upcoming release and will be merged into ``main`` 
+  once completed.
+* **Hotfix** - This is an exceptional type of branch that comes directly off ``main`` 
+  and is merged directly back into it. This would used when there is a major bug
+  needs fixing immediately.
 
 Release Model
 -------------
 
-The JADE project uses semantic versioning in the format Major.Minor.Patch with the choice of versioning increment
-for a specific release using the following guidelines but the final decision beign discrentionary.
+The JADE project uses semantic versioning in the format **Major.Minor.Patch** 
+with the choice of versioning increment for a specific release using the 
+following guidelines but the final decision beign discrentionary.
 
-#.	Major: Major or non-backwards compatable functionality additions such as a new transport code being added, the class structure being modified or the input/output directory structure is changed.
-#.	Minor: Addition of new features that are additive/backward compatible with the previous version. New Benchmarks will generally be at this level.
-#.	Patch: Fixes for bugs, typos, tidying code, and other small changes that do not change or extend JADE’s intended functionality.
+* **Major** - Major or non-backwards compatable functionality additions such as a 
+  new transport code being added, the class structure being modified or the 
+  input/output directory structure is changed.
+* **Minor** - Addition of new features that are additive/backward compatible with 
+  the previous version. New Benchmarks will generally be at this level.
+* **Patch** - Fixes for bugs, typos, tidying code, and other small changes that do
+  not change or extend JADE's intended functionality.
 
 Contribution steps
 ------------------
@@ -83,6 +104,11 @@ are as follows:
    repository with the same name under your personal account. As such, you can commit
    to it as you please without disrupting other developers.
 #. Clone locally your fork of JADE and create a new branch off of the ``Developing`` one.
+#. Setup your environment for developing JADE.
+  #. Install JADE (see :ref:`install`)
+  #. Install the pre-commit hooks (``pre-commit install``) and check they 
+     can run (``pre-commit run --all-files``).
+  #. Ensure you can run the tests (see :ref:`Testing In JADE <runtesting>`)
 #. Make your changes on the new branch that you intend to have included in ``Developing``.
 #. Issue a pull request from GitHub and select the ``Developing`` branch of JADE main
    repo as the target.
@@ -101,23 +127,25 @@ The following are minimum requirements necessary for the approval of a pull requ
 
 * the python code should adhere to the `PEP 8 <https://peps.python.org/pep-0008/>`_ convention.
   This can be achieved for intance using `pycodestyle <https://pypi.org/project/pycodestyle/>`_
-  as linter in your code editor of choice. Another (automatic) way, is to use the `black formatter 
-  <https://github.com/psf/black>`_
+  as linter in your code editor of choice. The 
+  `black formatter <https://github.com/psf/black>`_ should be run automatically
+  as part of the pre-commit hooks (see `Contribution steps`_).
 * if a new feature is developed, new test cases must be added to unit test suites.
-  `pytest <https://docs.pytest.org/en/7.4.x/>`_ must be used. Some additional info on this can be 
-  found at :ref:`testing`.
-* no conflicts are allowed with the ``Developing`` branch, i.e., the original ``Developing`` branch
-  should be pulled into the fork and all eventual conflicts resolved prior to the submission
-  of the pull request.
-* the new code shall not break any pre-existing feature, i.e., all unit tests and regression tests
-  are passed.
-* if a new feature is added, it should be properly reported in the sphinx documentation.
+  `pytest <https://docs.pytest.org/en/7.4.x/>`_ must be used. Some additional 
+  info on this can be found at :ref:`testing`.
+* no conflicts are allowed with the ``Developing`` branch, i.e., the original 
+  ``Developing`` branch should be pulled into the fork and all eventual 
+  conflicts resolved prior to the submission of the pull request.
+* the new code shall not break any pre-existing feature, i.e., all unit tests 
+  and regression tests are passed.
+* if a new feature is added, it should be properly reported in the sphinx 
+  documentation (see `Modify documentation using Sphinx`_).
 
 Modify documentation using Sphinx
 =================================
 
 This documentation is written with
-`Sphynx <https://www.sphinx-doc.org/en/master/index.html>`_ using a template
+`Sphinx <https://www.sphinx-doc.org/en/master/index.html>`_ using a template
 provided by `Read The Docs <https://readthedocs.org/>`_. Before attempting
 to modify the documentation, the developer should familiarize with these tools
 and with the RST language that is used to write it.