144 contribution guidelines: introduction and planning stage

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,44 @@
+# 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 reply on [this issue][new_member]
+
+??? tip "How to"
+    [How to clone][how_to_clone]
+
+## Open an issue to explain your work
+
+Before starting any coding, you need to explain what you intend on doing in a [GitHub Issue][github_issues].
+
+!!! warning "Check existing issues first"
+    Before opening an issue, please check if a similar issue is opened. If you find an opened issue, do you need an additional issue or does your proposed work fits within the current existing issue? Can the existing issue be amended to include your idea while staying on topic and of a reasonable size? Feel free to discuss this in the existing issue if you are unsure.
+
+The issue is where all discussions on planning how the work is going to be done should go. Comments in the issue can include discussions around:
+
+* finding the best place(s) in the code to implement your proposed changes.
+* identifying if the proposed work is of the appropriate size or if it should be split into smaller issues.
+* for bug reports, identifying the best fix.
+* if adding a new feature, finding the best name and location for the new namelist switch.
+
+!!! failure "Do not list the code changes you made to fix the issue"
+
+    An issue should not contain the detail of the code changes made and the modified files. That information is contained in the Git history of the code and does not need to be replicated by hand.
+
+### Considerations
+
+**Keep it on topic.** Issues should be self-contained logical units of work. Be wary of "also" which often indicates two unrelated changes are lumped together.
+
+**Not too big and not too small.** Remember all units of work will be reviewed, try to keep these to reasonable sizes to avoid lengthy review delays.
+
+**Explain the work.** If you want to propose a new algorithm, in your issue description give a reference(s) to the algorithm(s). Explain why you think if would be beneficial to have it in CABLE. Explain where you plan to implement it in the code if you know, or discuss this in the issue before starting working on it.
+
+If the issue is about a bug or a code improvement, explain why it is a bug. Give the solution if you know it. Give a reproducible test case that highlights the issue if possible.
+
+[how_to_clone]: resources/how_to.md#cloning-a-repository
+[github_issues]: https://github.com/CABLE-LSM/CABLE/issues
+[new_member]: https://github.com/CABLE-LSM/CABLE/issues/110

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

@@ -0,0 +1 @@
+# FAQs

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

@@ -0,0 +1,39 @@
+# 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>
+On your local machine in a terminal, clone the repository:
+
+```bash
+git clone <URL provided>
+```
+
+!!! tip "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, follow the steps:
+
+    1. Remove the current remote repository
+    ```
+    git remote rm origin
+    ```
+    2. Add the new remote repository
+    ```
+    git remote add origin <URL>
+    ```
+    3. Reset the connection between your local and remote branches (this can be done at any time). Do this for your current branch and `main` at least.  Checkout each branch you want to reset and type:
+    ```
+    git branch -u origin/<branch_name>
+    ```
+
+[CABLE-repo]: https://github.com/CABLE-LSM/CABLE