Working Practices

How to contribute to CMEW

First time contributor instructions

First time developers must follow the Wiki: First time developer instructions before starting any development.

Summary of branches

The default branch in this repository is called main. The main branch is stable and will never contain broken code.

All new developments occur in feature branches. Feature branches typically use the main branch as their parent branch.

An overview of the working practices

The working practices for the Climate Model Evaluation Workflow (CMEW) are based on the Git Feature Branch Workflow​.

Note

The GitHub: CMEW Project Board is used to manage work for CMEW. The "Product backlog" column contains issues that need to be refined. Issues in the "Product backlog" column are ordered. Please do not move or start work on these issues. During the CMEW planning meetings, issues will be moved from the "Product backlog" column to the "Sprint backlog" column and assigned to a developer, indicating that work on the issue can start. Issues in the "Sprint backlog" column are unordered.

The steps in the working practices that a developer must follow are:

• Select an issue from the "Sprint backlog" column that is assigned to you
• Mark the issue as "Development in progress" by moving the issue from the "Sprint backlog" column to the "Development in progress" column
• Create (and checkout) a new feature branch from main
• Activate the development environment
• Make changes:
  • Modify the code
  • Write tests and documentation
  • Validate the workflow locally
  • Run the tests locally
  • Build the documentation locally
  • Commit the code changes
  • Push the changes to GitHub
• Create a pull request (PR)
• Mark the issue as "Ready for review" by moving the PR to the "Ready for review" column
• Request a review
• Merge the feature branch into main

The following steps are automated:

• Mark the PR as "Review in progress":
  • The PR is automatically moved from the "Ready for review" column to the "Review in progress" column when a review is submitted.
• Mark the PR as "Approved":
  • The PR is automatically moved from the "Review in progress" column to the "Reviewer approved" column when the PR is approved.
• Mark the PR as "Done":
  • The PR is automatically moved from the "Reviewer approved" column to the "Done" column when the PR is merged.
• Remove the feature branch.
• Close the issue:
  • Closes #<issue_number>. is included in the first comment box of the PR. This links the PR to the issue, which enables the issue to be closed automatically when the PR is merged. GitHub: Linking a pull request to an issue provides more information.
  • The issue is automatically moved from the "Development in progress" column to the "Done" column when the issue is closed.

Requirements

The steps in the working practices can be accomplished using the method you are most comfortable with. However, the following requirements must be adhered to when contributing to CMEW:

1. Feature branch name format: Use the format <issue_number>_<short_description_of_feature> when naming new feature branches, to make it easier to determine how issues and branches are connected, for example, 5_develop_configure_task.
2. Making changes: Follow the Wiki: Developer Guide when making changes.
3. Commit message format: Follow the Commit message style guide for Git.
4. Pull request creation: Follow the PR checklist.
5. Review process: Follow the Wiki: Review Process when reviewing the changes.
6. Merge method: Use Squash and merge when merging feature branches into main.
7. Pull request commit message format: Use the format #<PR_number>: <issue_title> when writing the commit message for the pull request, so the pull request number is immediately visible on GitHub, regardless of the length of the pull request title.

Detailed Working Practices

• For those unfamiliar with Git / GitHub, a Wiki: Detailed Working Practices with example commands is available.