Merge branch '21-updates-to-external-contributor-section' into 'main'

Resolve "Updates to External Contributor Section"

Closes #21

See merge request !20

source/contrib.rst

@@ -164,60 +164,71 @@ Step 6: Make changes to your branch on your local machine
 
    git branch -a
 
-* Push your changes back to the forge for savekeeping
+* Stage your changes
 
 .. code-block:: bash
  
    git add path/fileyouchanged.F90
    git commit -m 'add comments about the changes'
-   git push origin
 
-* To update your local repository with changes make on the remote repository to your branch (perhaps by a collaborator or yourself on a different machine) use the fetch command:
+Step 7: Bring your branch up to date with the main
+==================================================================
 
-.. code-block:: bash
+Before you create a merge request you need to bring your branch up to date with the main of the NEMO reference by following these steps:
+
+1) Verify that the External Contributor fork is up to date. If you do not have the access right to update the fork, ask your NEMO System Team contact to do so for you:
+
+.. image:: _static/Ext_dev_update_fork.png
+   :align: center
+   :width: 90%
 
-   git fetch
+|
 
-Note that this fetches the updates but does not yet merge them. You can then review the differences:
+2) Update your local copy of the fork main:
 
 .. code-block:: bash
 
-   git diff
+   git switch main
+   git pull
 
-If you are happy, you can then merge these changes into your local repository:
+3) Merge the main into your branch
 
 .. code-block:: bash
 
-   git merge
+   git switch X-the-name-of-your-branch
+   git merge main
 
-Any changes you have made in your local workspace  will be preserved until you commit them, so you wont risk overwriting something you have recently edited by following these steps. 
+.. note::
 
-* If, however, you want to totally reset your local branch to that stored on the remote repository:
+   | If you have touched a past of the code that has simultaneously been edited by another developer, you will have the following message pop up:
 
 .. code-block:: bash
 
-   git reset --hard origin/<branch_name> 
+   CONFLICT: Merge conflict in filename.F90
+   Automatic merge failed: fix conflicts and then commit the result.
 
-Step 7: Bring your branch up to date with the main
-==================================================================
+4) Resolve conflicts if necessary by opening your file and accepting or rejecting the changes pointed out by "HEAD" meaning the head of your branch and "main" meaning the fork's main, arrows <<<<<<< and >>>>>>> show where lines have been removed or added.
+
+Then add your changed files 
+
+.. code-block:: bash
 
-Before you create a merge request you need to bring your branch up to date with the main of the fork (which is essentially a mirror of the continiously evolving NEMO reference).
+   git add filename.F90
+   git commit -m 'fix conflicts'
 
-First you should try to rebase your branch and resolve any conflicts. 
+5) Once you have resolved these conflicts you can push: 
 
 .. code-block:: bash
 
-   git rebase main
+   git push
 
-The idea here is that the changes that took place on the main while you were undertaking your developments are now moved to your branch giving the impression that your branch just started from the head of the main. This is a clean approach and helps with reviewing. 
+.. caution::
 
-Alternatively you can merge the main into your branch. This is a less desirable approach as it essentially adds all the developments that took place on the main to your own branch's history 
+   | If your branch is out of date with that stored on the Forge (due to changes made by yourself on another machine or contributions from a collaborator), you can totally reset your local branch:
 
 .. code-block:: bash
 
-   git merge main
-
-Once once this step has been completed can you finalize and proceed with a merge request. 
+   git reset --hard origin/<branch_name> 
 
 Step 8: Test your branch using SETTE
 ===============================================================
@@ -243,6 +254,8 @@ Once your developments have been tested and shown to not "break the code", you
 
 Here you can assign a reviewer (your designated NEMO System Team contact person) and give a description of the work that you did to aid the review process. 
 
+Once this merge is accepted, you developments will be added to the NEMO reference code. Please then go and close your issue on the External Contributor fork so that it is clear that this development is no longer outstanding. 
+
 Step 10: Update of documentation and development included in the NEMO reference 
 ===================================================================================