diff --git a/documentation/docs/developer_guide/contribution/develop_your_idea.md b/documentation/docs/developer_guide/contribution/develop_your_idea.md new file mode 100644 index 000000000..a9f3ecce9 --- /dev/null +++ b/documentation/docs/developer_guide/contribution/develop_your_idea.md @@ -0,0 +1,75 @@ +# Develop your idea + +After planning for the work, we enter the stage where it is time to implement the idea in the source code. + +This is a diagram view of how this stage proceed: + +```mermaid + flowchart LR + + %% Define all the nodes first + clone[Clone repository]:::uniq ; + locbranch(["Create local branch:
git checkout <branchname>"]):::term; + edits[Modify the source code]:::term; + add["Add your edits to git's index:
git add ."]:::term; + commit["Commit your edits locally:
git commit"]:::term; + push[Push your edits to GitHub:
git push]:::term; + pr([Create a pull request]):::github; + tests[\Do the tests pass?/]:::question; + review[Ready for review]; + + clone --> locbranch--> edits; + edits --> add --> commit --> push; + push --> |first time|pr --> tests; + push ----> |subsequent|tests; + tests -->|Yes|review; + tests -->|No|edits; + + classDef default fill:#FFFDE7, stroke:#FFF59D; + classDef uniq fill:#D81B60,stroke:#880E4F,color:#FFFFFF; + classDef github fill:#388E3C,stroke:#1B5E20,color:#FFFFFF; + classDef term fill:#F44336,stroke:#B71C1C,color:#FFFFFF; + classDef question fill:#6D4C41,stroke:#3E2723,color:#FFFFFF; + + linkStyle 9 stroke:red,color:red; + linkStyle 8 stroke:green,color:darkgreen; + + click review "https://cable.readthedocs.io/en/latest/developer_guide/contribution_flowchart/#review" "Review process" + +; +``` + +## 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. To learn more how to prepare for new work after finishing some contribution, please refer to the final steps documentation. + +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] + +## Create a branch for your issue + +Once you decide to start on an issue, you need two actions on GitHub CABLE's repository: + +1. [Assign yourself][assign_issue] to the issue. This indicates to the community you are activelly working on the issue. It does not have to be the same as the reporter of the issue. +2. [Create a branch][create_branch] on the repository for you to work on. This allows you to isolate your work from others' work, thus controlling the changes made to the code. + +!!! warning "Branch naming convention" + + We would like all branches to follow the GitHub naming convention: `-`. If your issue title is too long, some shortening in the branch name is acceptable. A branch created following the methodology above will follow that convention. + In VS Code, the GitHub Pull Requests and Issues extension allows you to specify the branch template in the settings: + ``` + "githubIssues.issueBranchTitle": "${issueNumber}-${sanitizedIssueTitle}" + ``` + +!!! tip "Branches are writable by all" + + Contrary to SVN, in GitHub, the branches are writeable by everyone. This means collaboration on code development can happen on all branches, there is no need to open special branches for collaboration. + +[how_to_clone]: resources/how_to.md#cloning-a-repository +[new_member]: https://github.com/CABLE-LSM/CABLE/issues/110 +[assign_issue]: +[create_branch]: \ No newline at end of file diff --git a/documentation/docs/developer_guide/contribution/plan_your_work.md b/documentation/docs/developer_guide/contribution/plan_your_work.md index b5d48b519..33180faca 100644 --- a/documentation/docs/developer_guide/contribution/plan_your_work.md +++ b/documentation/docs/developer_guide/contribution/plan_your_work.md @@ -28,6 +28,4 @@ The issue is where all discussions on planning how the work is going to be done 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 diff --git a/documentation/docs/developer_guide/contribution_guidelines.md b/documentation/docs/developer_guide/contribution_guidelines.md index 581aaeadd..f4e1d1e20 100644 --- a/documentation/docs/developer_guide/contribution_guidelines.md +++ b/documentation/docs/developer_guide/contribution_guidelines.md @@ -17,38 +17,6 @@ These guidelines are written from the perspective of a new contributor to CABLE The legend for all subsequent flowcharts can be found in the [legend section](#legend-for-the-flowcharts) -## 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] - -## Explain your work - -You first need to tell the community what you will be working on. For this you need to open an Issue on the CABLE's GitHub repository. - -### Open an issue - -
- ![Image title](../assets/issue.png){ width="90%", align=right } -
-Make sure to give a description that is detailed enough. The Issue should describe what you are trying to do and why and not how you are doing it. - -For example, if you want to implement an algorithm by Doe J. et al (1950), say so in your issue and ideally put a link to the publication (using a DOI). You can add why you think this is a good addition to CABLE: is it adding a completely new process? Is it adding a new parametrisation for an existing process? - -You can cite some of the source code if it helps explain what the issue is. - -!!! 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. - - An issue should be used to discuss and plan the work before it is implemented so the work done to fix the issue should not be commented on here but in the pull request. - ## A place for your work in the repository ```mermaid diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index ac8e12727..359e49457 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -100,6 +100,7 @@ nav: - Contribution guidelines: - developer_guide/contribution/index.md - developer_guide/contribution/plan_your_work.md + - developer_guide/contribution/develop_your_idea.md - developer_guide/contribution/resources/how_to.md - Documentation guidelines: - developer_guide/documentation_guidelines/index.md