Merge pull request #37320 from mantidproject/35829_documentation_for_…

…build_packages_from_branch

Add documentation for build_packages_from_branch jenkins job

dev-docs/source/Packaging.rst

@@ -118,6 +118,59 @@ The ``--package-suffix`` argument is an optional string to append to the name
 of the final package. We generally pick ``Unstable`` for installers not built
 by the CI pipeline to indicate it has been built outside of the standard process.
 
+.. _build_packages_from_branch:
+
+Build packages from branch using Jenkins
+----------------------------------------
+
+Developers can build packages to test branches using the ``build_packages_from_branch`` `Jenkins job <build_packages_from_branch_job_>`_. This job provides the ability to,
+
+- Run system tests on Windows, Mac, Linux, or all three.
+- Build a packages on Windows, Mac, Linux, or all three.
+- Publish the package(s) to a given Anaconda channel and label.
+- Publish the package(s) to a given Github repository under a specified tag.
+
+for a given branch of mantid. The branch can be from the main mantid repo or from a remote.
+
+Options
+#######
+
+- ``BUILD_DEVEL`` [``none``, ``all``, ``linux-64``, ``win-64``, ``osx-64``]: Run the system tests for this OS.
+- ``BUILD_PACKAGE`` [``none``, ``all``, ``linux-64``, ``win-64``, ``osx-64``]: Build a package on this OS.
+- ``PACKAGE_SUFFIX``: String to append onto the standalone package name, useful for distinguishing builds. By default this is ``Unstable``.
+- ``PUBLISH_TO_ANACONDA``: Set true to publish to the given Anaconda channel and label.
+- ``PUBLISH_TO_GITHUB``: Set true to publish to the Github repository using the specified tag.
+- ``ANACONDA_CHANNEL``: Anaconda channel to upload the package to. By default this is ``mantid``.
+- ``ANACONDA_CHANNEL_LABEL``: Label attached to the uploaded package. By default this is ``unstable``.
+- ``GITHUB_RELEASES_REPO``: Repository to store the release. By Default this is ``mantidproject/mantid``.
+- ``GITHUB_RELEASES_TAG``: Name of the tag for the release; only to be used for release candidate builds.
+- ``ANACONDA_TOKEN_CREDENTIAL_ID`` [``anaconda-cloud-token``, ``anaconda-token-ornl``]: One of two credentials to use for publishing to Anaconda.
+- ``GH_ORGANIZATION_OR_USERNAME``: Name of the organisation or Github user name who owns the repository with the code to build. By default this is ``mantidproject``, if you are building from a fork this will need to change to your username.
+- ``BRANCH_NAME``: Name of the branch to build the packages from.
+
+Example
+#######
+
+Say I've implemented a new file searching method on a branch ``1234_new_file_search`` and I want to test this on IDAaaS, one of the easiest ways to do this would be to build the packages and upload them to Anaconda using the pipeline. These are the steps I'd take to do this.
+
+1. Go to the ``build_packages_from_branch`` `Jenkins job <build_packages_from_branch_job_>`_.
+2. If needed click ``login`` in the top right of the window.
+3. Go to ``Build with parameters`` in the side bar.
+4. Fill out the following options:
+
+   - ``BUILD_DEVEL`` = ``none``
+   - ``BUILD_PACKAGE`` = ``linux-64``
+   - ``PUBLISH_TO_ANACONDA`` = true
+   - ``ANACONDA_CHANNEL_LABEL`` = ``new_file_system_test``
+   - ``ANACONDA_TOKEN_CREDENTIAL_ID`` = ``anaconda-cloud-token``
+   - ``BRANCH_NAME`` = ``1234_new_file_search``
+
+5. Click ``Build``. This will take you back to the main job page, the build just set off will be the most recent (highest number) build on the left hand side. It is a good idea to make note of the build number / copy the link somewhere safe. If the build is for testing a pr, make sure to add the link to the testing instructions.
+6. Once the job has successfully completed, check `the Mantid Anaconda page <mantid-conda-org_>`_ to make sure it has uploaded.
+7. Head to IDAaaS (or any linux system) and run ``mamba install -c mantid/label/new_file_system_test mantidworkbench`` in a new environment to install the test package.
+
+Most often, you won't need to upload the packages to Anaconda, this is most useful in cases where installing standalone packages is inconvenient. Standalone package builds created by the jenkins job can be found under the jenkins job build artifacts, this is near the top of the page. Say you built a package for Windows using the jenkins job, you should find a ``mantidworkbench`` exe file in the build artifacts.
+
 
 .. _conda: https://conda.io
 .. _mantid-conda-recipes: https://github.com/mantidproject/mantid/tree/main/conda
@@ -130,4 +183,4 @@ by the CI pipeline to indicate it has been built outside of the standard process
 .. _download-page: https://download.mantidproject.org
 .. _nsis: https://sourceforge.net/projects/nsis/
 .. _dmg: https://en.wikipedia.org/wiki/Apple_Disk_Image
-.. _standalone-scripts: https://github.com/mantidproject/mantid/blob/main/installers/conda
+.. _build_packages_from_branch_job: https://builds.mantidproject.org/job/build_packages_from_branch/