Merge pull request #24604 from martyngigg/dev-docs-pr

Improve developer documentation around pull request reviews

dev-docs/source/GitWorkflow.rst

@@ -94,8 +94,31 @@ When creating a pull request you should:
 
 A good example is `here <https://github.com/mantidproject/mantid/pull/18713>`__.
 
-Recommended reading: `How to Write the Perfect Pull Request
-<https://github.com/blog/1943-how-to-write-the-perfect-pull-request>`_
+Recommended reading: `How to Write the Perfect Pull Request <https://github.com/blog/1943-how-to-write-the-perfect-pull-request>`_
+
+For further information about the review process see :ref:`reviewing a pull request <ReviewingAPullRequest>`.
+
+To check out a particular pull request for functional testing use the following commmands:
+
+.. code-block:: sh
+
+   git fetch <main-remote-name>  +pull/<ID>/merge:pr/<ID>-merged
+   git checkout pr/<ID>-merged
+
+where ``<ID>`` is the pull request number given on GitHub and ``<main-remote-name>`` is the name
+of the remote pointing to the original ``mantid`` repository. If you cloned directly from `mantid <https://github.com/mantidproject/mantid>`_
+then ``main-remote-name=origin`` else if you cloned from a fork then it is the name of remote that points
+back to the original repository.
+
+Note that these commands will checkout a temporary branch that has the development branch merged with master and not just
+the development branch on its own. This command can be aliased by adding the following to the ``[alias]]`` section of your ``~/.gitconfig``
+file:
+
+.. code-block:: sh
+
+   test-pr=!f() { git fetch <main-remote-name> +pull/$1/merge:pr/$1-merged && git checkout pr/$1-merged; }; f
+
+where again ``<main-remote-name>`` has the same meaning as above
 
 Stale Pull Requests
 -------------------

dev-docs/source/IndividualTicketTesting.rst → dev-docs/source/ReviewingAPullRequest.rst

-.. _IndividualTicketTesting:
+.. _ReviewingAPullRequest:
 
-=========================
-Individual Ticket Testing
-=========================
+========================
+Reviewing a Pull Request
+========================
 
 An important step in our :ref:`development workflow <GitWorkflow>` is the testing of individual issues/tickets after the development on them is complete, and before the code is merges into the master branch. Developers pick one from `the list <https://github.com/mantidproject/mantid/pulls>`_ of completed issues and perform a number of verification steps on it. The mechanics of testing a pull request (e.g. the git commands to use) are described :ref:`here <GitWorkflow>`. This page is concerned with the aspects that should be considered in deciding whether a pull request should be recommended to merge or sent back to the developer for further work. *There should be very little reluctance to reopen a ticket even for minor issues.*
 

dev-docs/source/index.rst

@@ -139,7 +139,7 @@ Testing
    RunningTheUnitTests
    DebuggingUnitTests
    UnitTestGoodPractice
-   IndividualTicketTesting
+   ReviewingAPullRequest
    WritingPerformanceTests
    SystemTests
    DataFilesForTesting
@@ -154,8 +154,8 @@ Testing
 :doc:`UnitTestGoodPractice`
    Guidance on writing good unit tests.
 
-:doc:`IndividualTicketTesting`
-   What to expect and inspect when reviewing an individual contribution to mantid.
+:doc:`ReviewingAPullRequest`
+   What to do when reviewing an individual contribution to mantid.
 
 :doc:`WritingPerformanceTests`
    A walk through of how to write a performance test.
@@ -208,6 +208,7 @@ Component Overviews
    MultiThreadingInAlgorithms
    PythonVSCppAlgorithms
    RemoteJobSubmissionAPI
+   Widgets/Plotting
    Workbench
    WritingAnAlgorithm
    WritingCustomConvertToMDTransformation