-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
#131- reorganise the contribution guidelines
- Loading branch information
Showing
5 changed files
with
86 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
13 changes: 13 additions & 0 deletions
13
documentation/docs/developer_guide/contribution/plan_your_work.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
24 changes: 24 additions & 0 deletions
24
documentation/docs/developer_guide/contribution/resources/how_to.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters