Development and pull request. Fixes #147

documentation/docs/developer_guide/contribution/develop_your_idea.md

@@ -74,11 +74,20 @@ Once you decide to start on an issue, you need two actions on GitHub CABLE's rep
 
 It is now time for you to start working on CABLE and its documentation. Here are a few considerations and advice to consider during your coding work:
 
-1. Follow CABLE's coding standard for all new work
-2. Document your additions/modifications to the code as you go along, according to the documentation guidelines. Consider being a good citizen by adding more documentation to existing parts of the code if you can!
-3. Keep every commit small. Write meaningful commit messages about what you want to achieve rather than a description of the change. The committed code itself is the description of the change and is often more precise than you can be. (see examples after)
-4. Reference the issue number in each commit message. Do not put it at the start of the message since `#` is a comment in shell scripting. (see examples after)
-
+1. Follow [**CABLE's coding standards**][coding_standards] for all new work.
+2. **Implement new features within a new namelist option.** New features should be turned off by default. All new namelist options will require updates to the documentation.
+3. **Document your additions/modifications** to the code as you go along, according to the [documentation guidelines][doc_guidelines]. Keep in mind the science needs to be documented within the source code using FORD. Modifications to the User Guide are also done within this CABLE repository and are done using Markdown formatting. Consider being a good citizen by adding more documentation to existing parts of the code if you can!
+4. **Keep every commit small.** **Write meaningful commit messages** about what you want to achieve rather than a description of the change. The committed code itself is the description of the change and is often more precise than you can be. (see examples after)
+5. **Reference the issue number (format: `#<number>`) in each commit message.** Do not put it at the start of the message since `#` is a comment in shell scripting. (see examples after)
+6. **Push your work to the GitHub repository frequently.** For periods of active code development, this could happen daily or weekly. Pushing after each commit is also acceptable. It provides you with:
+    1. a backup
+    2. the possibility to work from different computers
+    3. easy collaboration as any CABLE developer can access an up-to-date version of your branch right away
+    4. a platform for getting support from the CABLE maintainers (see [The Pull Request: your communication centre](#the-pull-request-your-communication-centre))
+7. **Keep your branch current with the released versions of CABLE.** You are expected to merge into your branch the released versions of CABLE. We will only accept contributions from branches that are up-to-date with the latest released version of CABLE. An exception will be made for legacy work that as start a significant amount of time before the transition to git and GitHub.
+8. **[Create a Pull Request (PR)][pr_create] on GitHub early on**, ideally after the first commit on your branch. PRs allow the community to know what is being worked on. Keep your PR up-to-date by pushing your work frequently to GitHub.
+9. **Test frequently** (see [Testing your work][testing]).
+
 !!! tip "Examples of commit messages"
     Let's say you modified the value of the parameter, `my_param`, from 0.5 to 0.9 because you have read some paper that has proven the updated value is better.
 
@@ -90,7 +99,19 @@ It is now time for you to start working on CABLE and its documentation. Here are
 
     :white_check_mark: Use Doe J. et al. (2500) value for my_param. Fixes #123
 
+## The Pull Request: your communication centre
+
+The Issue is central to plan the work but once the work is being implemented, all discussions around the implementation or review will be done via the pull request. We will also consider the list of open pull requests to represent the current developments happening on CABLE.
+
+PRs require a description when you open them, this description and the PR title are editable. Our advice is to update them as your work progress as you may realise the scope of your PR changes later on. We will provide a template for the PR description, please read carefully and provide as much of the required information as possible.
+
+If you have any questions about the implementation of a feature, you can contact another CABLE developer or the CABLE maintainers team via the PR. Simply mention the people you'd like to contact in a comment with your question. For questions on lines of code you have modified, you can leave your comment right with the code which can reduce the risk of confusion.
+
 [how_to_clone]: resources/how_to.md#cloning-a-repository
 [new_member]: https://github.com/CABLE-LSM/CABLE/issues/110
 [assign_issue]: resources/how_to.md#assign-an-issue
-[create_branch]: resources/how_to.md#create-a-branch
+[create_branch]: resources/how_to.md#create-a-branch
+[pr_create]: resources/how_to.md#create-a-pull-request-pr
+[coding_standards]: ../coding_standards.md
+[testing]: testing.md
+[doc_guidelines]: ../documentation_guidelines/index.md

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

@@ -62,4 +62,6 @@ Since we want to enforce a branch naming convention for CABLE, the simplest is t
       ![how local branch](../../../assets/terminal_branch_create.png){ width="40%", align=left }
     </figure>
 
+## Create a pull request (PR)
+
 [CABLE-repo]: https://github.com/CABLE-LSM/CABLE

documentation/docs/developer_guide/contribution/testing.md

@@ -0,0 +1 @@
+# Testing your work