WP - planning - #131

documentation/docs/developer_guide/contribution/index.md

@@ -2,7 +2,7 @@
 
 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. 
+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.
 

documentation/docs/developer_guide/contribution/plan_your_work.md

@@ -6,8 +6,35 @@
 
     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]
+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]
 
-[How to clone][how_to_clone]
+??? 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.
+
+### 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. What you think the solution should be, 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

@@ -6,19 +6,22 @@ Below you will find details instructions on how to follow various steps of the c
 
 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 }
+  ![Image title](../../../assets/clone.png){ width="90%", align=right }
 </figure>
-!!! warning "Change the protocol after cloning"
+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, check our FAQs. 
+    To do this, check our [FAQs][FAQs]. 
 
-On your local machine in a terminal, clone the repository:
-
-```bash
-git clone <URL provided>
-```
+[CABLE-repo]: https://github.com/CABLE-LSM/CABLE
+[FAQs]: FAQs.md

documentation/mkdocs.yml

@@ -100,6 +100,7 @@ nav:
     - developer_guide/index.md
     - Contribution guidelines:
       - developer_guide/contribution/index.md
+      - developer_guide/contribution/plan_your_work.md
     - Contribution flowchart: developer_guide/contribution_flowchart.md
     - Documentation guidelines: 
       - developer_guide/documentation_guidelines/index.md