Initial gh wps (#408)

Co-authored-by: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com>

Author: james-bruten-mo

source/WorkingPractices/forking.rst

@@ -0,0 +1,85 @@
+.. _forking:
+
+Creating and Managing Forks
+===========================
+
+.. tip::
+
+    For more information see the `github documentation <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks>`_
+
+Forks are repositories that share code and visibility settings with the upstream repository. They provide a place for development work to take place while allowing the upstream repo to maintain limited write access. Forks can all merge branches with each other as well as with the upstream repository, meaning a pull request can be opened to merge a branch in a fork into the upstream main.
+
+Creating a Fork
+---------------
+
+Creating a fork is something that only needs to be done once per upstream repository. Once created, branches can be created in the fork as desired by the owner.
+
+.. tab-set::
+
+    .. tab-item:: Web Browser
+
+        First navigate to the upstream repository you wish to fork. Then select the fork button.
+
+        .. image:: images/gh_screenshots/fork_button_light.png
+            :class: only-light
+
+        .. image:: images/gh_screenshots/fork_button_dark.png
+            :class: only-dark
+
+        On the next page you can rename your fork if desired and select which branches to fork - ensure this box is unticked to fork all branches.
+
+        .. important::
+
+            Ensure the option to only clone the default branch is unticked.
+
+        .. image:: images/gh_screenshots/fork_page_light.png
+            :class: only-light
+
+        .. image:: images/gh_screenshots/fork_page_dark.png
+            :class: only-dark
+
+    .. tab-item:: gh cli
+
+        Run the following command, substituting for the required upstream owner and repository name,
+
+        .. code-block::
+
+            gh repo fork <OWNER>/<REPO>
+
+        .. tip::
+
+            Add ``--clone`` to immediately clone the forked repo
+
+
+Maintaining a Fork
+------------------
+
+Most work to maintain a fork involves syncing it with the upstream repository. Syncing a fork will ensure that changes to the upstream repository are copied into the fork. Syncing is done on a per branch basis. For example, after a new release, syncing the ``stable`` branch will ensure the forks ``stable`` branch contains the newly released code.
+
+.. important::
+
+    It is recommended that developers do not modify the synced branches from upstream in their forks as this may cause issues with merge conflicts when syncing a fork. Instead all work should be carried out in a branch.
+
+.. tab-set::
+
+    .. tab-item:: Web Browser
+
+        Navigate to your fork in github that you wish to sync. Select the ``Sync Fork`` button and if required, update the branch. This will only sync the branch you are currently on - to sync other branches select one from the branch dropdown menu. You may want to sync both ``stable`` and ``main``, particularly at a release.
+
+        .. image:: images/gh_screenshots/sync_fork_light.png
+            :class: only-light
+
+        .. image:: images/gh_screenshots/sync_fork_dark.png
+            :class: only-dark
+
+    .. tab-item:: gh cli
+
+        Run the following command, substituting for the downstream fork owner and repo name. Without the ``-b`` option, only the default branch will be synced. You may want to sync both ``stable`` and ``main``, particularly at a release.
+
+        .. code-block::
+
+            gh repo sync <OWNER>/<REPO> -b <BRANCH>
+
+        .. tip::
+
+            When using the gh cli to sync forks, remember that it won't pull the changes to local clone, this needs to be done manually.

source/WorkingPractices/gh_authorisation.rst

@@ -0,0 +1,11 @@
+.. _gh_authorisation:
+
+Setting Up Github Authorisations
+================================
+
+A brief overview of how to set up authorisations to gh for Sim Sys or links to relevant instructions.
+
+* ssh keys
+* verified commits
+* gh command line
+* Maybe more?

source/WorkingPractices/gh_dev_init.rst

@@ -0,0 +1,144 @@
+.. _gh_dev_init:
+
+Beginning a Github Development
+==============================
+
+This section will guide you through the development process assuming you are already authorised with github (:ref:`gh_authorisation`) and have already created a fork (:ref:`forking`).
+
+Create an Issue
+---------------
+
+.. important::
+
+    It is not guaranteed that opening an issue will result in action or even visibility by the relevant maintainers or code owners. If you think a team or individual should be aware of an issue, then contact them directly in addition to opening an issue.
+
+An issue in github can be used to document a problem in the codebase or as somewhere to document the development process for a new feature. Sub-issues can also be created if a large piece of work wants breaking down into smaller sections. If you are working on an issue, then assign yourself to it so that others know that you are working on it. Issues are created in the upstream repository.
+
+.. tab-set::
+
+    .. tab-item:: Web Browser
+
+        Navigate to the ``Issues`` tab for the relevant **upstream** repo and select the ``New Issue``. Write an suitable title and description, and use the options on the right as desired/appropriate.
+
+        .. image:: images/gh_screenshots/issues_light.png
+            :class: only-light
+
+        .. image:: images/gh_screenshots/issues_dark.png
+            :class: only-dark
+
+    .. tab-item:: gh cli
+
+        The following command can be used to create an issue from the command line. The available options can be seen in the `gh cli documentation <https://cli.github.com/manual/gh_issue_create>`_.
+
+        .. code-block::
+
+            gh issue create -R <OWNER>/<REPO> [options]
+
+There is no requirement to open an issue before making a pull request, as long as the change documentation is sufficient. For instance, small changes may not benefit from the separate issue.
+
+
+Clone the Repository
+--------------------
+
+A clone is a local copy of a repository - you can have a local clone of either an upstream repository or a fork. A clone will have an active branch which will initially be the default branch of the repository. All other branches in the repository can be accessed using the ``checkout`` command (see below). For general development, you should now get a clone of your fork.
+
+.. tip::
+
+    For those familiar with svn/fcm, a clone is the git equivalent to a working copy. However, unlike a working copy, which can only access a single branch, a clone can be switched to any branch in the repository.
+
+.. tab-set::
+
+    .. tab-item:: git commands
+
+        To clone a repository using git, run the following in a terminal:
+
+        .. code-block::
+
+            git clone <URL> <CLONE_NAME>
+
+        where ``CLONE_NAME`` is the desired directory name of the clone. It will default to the name of the repository.
+
+        The ``URL`` can be found from github,
+
+        .. image:: images/gh_screenshots/clone_button_light.png
+            :class: only-light
+
+        .. image:: images/gh_screenshots/clone_button_dark.png
+            :class: only-dark
+
+        selecting the url as desired.
+
+    .. tab-item:: gh cli
+
+        To clone a repository using gh cli run the following command,
+
+        .. code-block::
+
+            gh repo clone <OWNER>/<REPO> <CLONE_NAME>
+
+        where ``CLONE_NAME`` is the desired directory name of the clone. It will default to the name of the repository.
+
+        .. tip::
+
+            Using gh cli to clone a fork will automatically add the upstream repository as a remote source which can be helpful.
+
+
+Create a Branch
+---------------
+
+Branches for developing Simulation Systems repositories should generally be branched from ``stable`` where this exists (some smaller repositories only contain a ``main`` branch). Creating a branch from ``main`` may be acceptable if the development is continuing on from a ticket already committed at that release.
+
+To create a branch and switch to it from the command line, the syntax is,
+
+.. code-block::
+
+    git branch <branch_name> <parent_branch>
+    git checkout <branch_name>
+
+    # or
+
+    git checkout <parent_branch>
+    git checkout -b <branch_name>
+
+.. note::
+
+    It is also possible to create a new branch via github in a web browser.
+
+
+Developing a Change
+-------------------
+
+Now that you have a new branch, you are ready to begin development. See :ref:`development_index`, for advice on how to plan and implement new developments in a Simulation Systems repository, including advice on Metadata, KGO's and testing.
+
+.. tip::
+
+    To see the status of your current clone you can run ``git status``
+
+While developing you will likely want to commit your changes and push to the remote repository. First you will need to stage any files that have been modified and you would like to include in your commit,
+
+.. code-block::
+
+    git add path/to/file1 [path/to/file2...]
+
+And then commit the change,
+
+.. code-block::
+
+    git commit -m "An Informative Commit Message"
+
+.. tip::
+
+    In git you do not need to commit all modified files unlike in svn/fcm. It is also possible to only commit certain parts of a modified file. For more information see the relevant man page, ``man git add``.
+
+Finally, you may want to push any commits stored in your local clone.
+
+.. code-block::
+
+    git push
+
+.. important::
+
+    Unlike svn/fcm, committing in git will not push your changes to the remote server. The ``git push`` command must also be used to do this.
+
+
+