Development Workflow

The glamod-nuim Development Workflow is based on the Feature Branch Workflow​.

Summary of branches

• The master branch: this branch will be stable and will never contain broken code (eventually)
• Feature branches: each new feature resides in its own branch; feature branches use master as their parent branch

First time developers

• Clone the repository:

cd <path_to_where_you_want_to_clone_to> 
git clone [email protected]:glamod/glamod-nuim.git 
cd glamod-nuim

Basic Workflow

• Create an issue
• Create a new feature branch
• Modify the code
  • Write tests and documentation
  • Run the tests locally
  • Build the documentation locally
  • Commit the code changes
• Create a pull request
• Review the code changes
• Merge the pull request
• Remove the feature branch
• Close the issue

Create an issue

• If an issue has not yet been created, create one here

Create a new feature branch

• Once/If implemented, activate the development environment for the current session (the following command only needs to be executed once per session):

conda activate glamod_nuim

• Checkout and update the master branch:

cd <path_to>/glamod-nuim
git checkout master
git pull

• Create and checkout a new feature branch from the master branch, where <feature_branch_name> is <issue_number>_<short_description_of_feature>, e.g. 27_plot_monthly_pressure_anomalies:

git checkout -b <feature_branch_name>

• Share the feature branch to GitHub:

git push --set-upstream origin

Modify the code

git add <new_file>

Write tests and documentation

• See TBC

Run the tests locally

• Run the tests:

cd <path_to>/glamod-nuim
pytest

(pytest auto-discovers tests, see pytest: Conventions for Python test discovery)

• Run Coverage:

coverage run
coverage report

Build the documentation locally

• Build the documentation (once created):

cd <path_to>/glamod-nuim/doc
make html

• View the documentation:

gio open build/html/index.html

Commit the code changes

• Commit all local and staged changes:

git commit -am "#<issue_number>: <descriptive_commit_message>"

• If one or more of the pre-commit git hooks fail, the git commit command will fail; local modifications to the code will be made, except in the case of flake8, where changes will need to be made manually
• Commit all local and staged changes again:

git commit -am "#<issue_number>: <descriptive_commit_message>"

(use black --diff . to see the changes Black would make without making local modifications to the code)

• Share the changes to GitHub:

git push

Create a pull request

• Create either a PR or, if the changes aren't quite ready for review, a draft PR, see GitHub: Creating the pull request; also:
  • in the main section of the page:
    • ensure master is selected as the base branch
    • use the same title as the issue
    • add Closes #<issue_number>. in the description of the PR to automatically link the PR to the issue, see GitHub: Linking a pull request to an issue
    • if the PR is dependent on other PRs, add details in the description after the above comment
  • on the right hand side of the page, click on the cog symbol to the right of:
    • Reviewers to add (ideally) two or more reviewers (aim to have at least two approvals before merging)
    • Assignees to add yourself as an assignee
    • Milestone to add the milestone if needed
• If a draft PR was created, once the changes are ready for review, mark the PR as ready for review, see GitHub: Marking a pull request as ready for review; only at this point will the reviewers be notified

Review the code changes

• See the Wiki: Review Process
• Optionally test the code locally as a reviewer:
  • For first time reviewers, follow First time developers
  • Follow Checkout and update the main branch
  • Checkout the feature branch to be reviewed: git checkout <feature_branch_name>
  • Follow Run the tests locally

Merge the pull request

• Once (ideally) two Reviewers have approved the PR, merge the PR, see GitHub: Merging a pull request:
  • ensure Squash and merge is selected by using the down arrow to the right of the green button
  • click the green Squash and merge button
  • move the PR number from the end of the message to the start of the message, e.g. #<PR_number>: <issue_title>
  • click the green Confirm squash and merge button
• If the PR is unable to be merged due to merge conflicts, resolve the conflicts, either via the web editor or the command line, see GitHub: Resolving a merge conflict on GitHub, then run the tests to ensure the tests still pass:

git checkout main
git pull
git checkout <feature_branch_name>
git merge main
<resolve merge conflicts>
git commit -am "#<issue_number>: Merge latest changes from main"

Remove the feature branch

• Once the PR has been merged, click the Delete branch button, see GitHub: Deleting a branch used for a pull request
• Remove the local branch:

git branch -d <feature_branch_name>

• Remove stale references associated with origin

git remote prune origin

Close the issue

• If the PR was correctly linked to the issue as described in the GitHub: Create a pull request section, the issue will already be closed