#131- reorganise the contribution guidelines

documentation/docs/developer_guide/contribution/index.md

@@ -0,0 +1,45 @@
+# Contribution guidelines
+
+All new contributors are encouraged to read through these guidelines before working on any development work. All contributors should refer to these guidelines if they have questions on the contribution process.
+
+These guidelines are written from the perspective of a new contributor to CABLE wanting to start their first development. Notes are added when guidelines for subsequent contributions differ. 
+
+:material-sim-alert: The CABLE documentation is an integral part of the CABLE code and its repository. The present guidelines apply for changes to the scientific code as well as to the documentation. As such all subsequent reference to "source code" or "code" apply to the code itself or its documentation. All changes to the scientific code **must** be accompanied by adequate changes to the documentation. The changes to the documentation are expected to be part of the same set of changes as the scientific modifications. The documentation changes **must** not be submitted separately, except for corrections. You can refer to [the documentation guidelines][doc-guidelines] to know what level of documentation is expected and how to document code changes.
+
+!!! warning "Pre-requisite before contributing to CABLE"
+
+    Before contributing to CABLE, please ensure you have followed all the steps to [setup Git and GitHub][git-training] given by ACCESS-NRI. Failing this, some of the commands described here may require additional steps or options.
+
+!!! info "Resources"
+
+    Please refer to [this cheat sheet page][cheatsheet] for quick references to Git, Markdown and FORD syntax.
+
+## Process overview
+
+Here is a flowchart explaining how the various steps of the contribution workflow interact together. More details are provided for each step in the following sections of this guide.
+
+```mermaid
+   flowchart TD
+
+   Copy[Get your copy of the software]
+   Idea[Explain your work in an issue]
+   Workspace[Create a place for your work for you in the repository]
+   Work[Do your work, record it and check it]
+   Review[Get a review on your work]
+   Merge[Get your work into <br> the main development version of CABLE]
+   FinalUpdate[Get ready for your next project]
+
+   Copy --> Idea --> Workspace --> Work;
+   Work -->|Incorrect|Work;
+   Work -->|Correct|Review;
+   Review -->|Apply requested changes|Work;
+   Review -->|Approved|Merge --> FinalUpdate;
+
+   linkStyle 4 stroke:red,color:red;
+   linkStyle 3 stroke:green,color:green;
+   linkStyle 2 stroke:red,color:red;
+   linkStyle 5 stroke:green,color:green;
+;
+```
+
+[doc-guidelines]: documentation_guidelines/index.md

documentation/docs/developer_guide/contribution/plan_your_work.md

@@ -0,0 +1,13 @@
+# Plan your work
+
+## Get your copy of the software
+
+!!! note "First time only"
+
+    You only need to clone the repository on your work machine the first time you work on a development for CABLE. The subsequent times, you can work from the same copy of the repository.
+
+If you are a member of the CABLE-LSM organisation on GitHub, you can simply work from a locally cloned copy of the repository. You do not need to create a fork of the GitHub repository. To become a member of the CABLE-LSM organisation, please open an issue on [the CABLE repository][https://github.com/CABLE-LSM/CABLE/issues/new]
+
+[How to clone][how_to_clone]
+
+[how_to_clone]: resources/how_to.md#cloning-a-repository

documentation/docs/developer_guide/contribution/resources/how_to.md

@@ -0,0 +1,24 @@
+# How-tos for the contribution steps
+
+Below you will find details instructions on how to follow various steps of the contribution guidelines with GitHub and git.
+
+## Cloning a repository
+
+On [CABLE's GitHub main page][CABLE-repo], click the `code` green button, choose the SSH protocol and copy the URL you need:
+<figure markdown>
+  ![Image title](../assets/clone.png){ width="90%", align=right }
+</figure>
+!!! warning "Change the protocol after cloning"
+
+    It is possible to change the access protocol to GitHub in your cloned repository if you realise you have chosen the wrong protocol, ie.:
+
+    - you have cloned using the HTTPS protocol but have SSH keys setup with GitHub
+    - or you have cloned using the SSH protocol but you have a personal access token setup with GitHub
+
+    To do this, check our FAQs. 
+
+On your local machine in a terminal, clone the repository:
+
+```bash
+git clone <URL provided>
+```

documentation/docs/developer_guide/contribution_guidelines.md

@@ -4,38 +4,15 @@
 
     Before contributing to CABLE, please ensure you have followed all the steps to [setup Git and GitHub][git-training] given by ACCESS-NRI. Failing this, some of the commands described here may require additional steps or options.
 
-These guidelines are written from the perspective of a new contributor to CABLE wanting to start their first development. Notes are added when guidelines for subsequent contributions differ.
+These guidelines are written from the perspective of a new contributor to CABLE wanting to start their first development. Notes are added when guidelines for subsequent contributions differ. 
 
 :material-sim-alert: The CABLE documentation is an integral part of the CABLE code and its repository. The present guidelines apply for changes to the scientific code as well as to the documentation. All changes to the scientific code **must** be accompanied by adequate changes to the documentation. The changes to the documentation are expected to be part of the same set of changes as the scientific modifications. The documentation changes **must** not be submitted separately, except for corrections. You can refer to [the documentation guidelines][doc-guidelines] to know what level of documentation is expected and how to document code changes.
 
 !!! info "Resources"
 
     Please refer to [this cheat sheet page][cheatsheet] for quick references to Git, Markdown and FORD syntax.
 
-First, here is a flowchart explaining how the various steps of the workflow interact together. More details are provided for each step in the following sections of this page.
 
-```mermaid
-   flowchart TD
-
-   Idea[Explain your work in an issue]
-   Workspace[Create a place for your work for you in the repository]
-   Work[Do your work, record it and check it]
-   Review[Get a review on your work]
-   Merge[Get your work into <br> the main development version of CABLE]
-   FinalUpdate[Get ready for your next project]
-
-   Idea --> Workspace --> Work;
-   Work -->|Incorrect|Work;
-   Work -->|Correct|Review;
-   Review -->|Apply requested changes|Work;
-   Review -->|Approved|Merge --> FinalUpdate;
-
-   linkStyle 4 stroke:red,color:red;
-   linkStyle 3 stroke:green,color:green;
-   linkStyle 2 stroke:red,color:red;
-   linkStyle 5 stroke:green,color:green;
-;
-```
 !!! info "Legend of flowcharts"
 
     The legend for all subsequent flowcharts can be found in the [legend section](#legend-for-the-flowcharts)
@@ -323,4 +300,4 @@ git branch --delete <branchname>
 [git-training]: https://access-nri.github.io/Training/HowTos/GitAndGitHub/
 [CABLE-repo]: https://github.com/CABLE-LSM/CABLE
 [cheatsheet]: documentation_guidelines/cheat_sheets.md
-[doc-guidelines]: documentation_guidelines/index.md
+

documentation/mkdocs.yml

@@ -98,6 +98,8 @@ nav:
     - Obsolete and deprecated features: user_guide/obsolete_and_deprecated_features/obsolete_and_deprecated_features.md
   - Developer Guide:
     - developer_guide/index.md
+    - Contribution guidelines:
+      - developer_guide/contribution/index.md
     - Contribution flowchart: developer_guide/contribution_flowchart.md
     - Documentation guidelines: 
       - developer_guide/documentation_guidelines/index.md