1. Working on a recipe

Maybe you have code to do something that does not yet exist within cosima-recipes and you would like to submit that as an Example. Or maybe you have found a more efficient way to run something on existing recipes, you've identified and fixed a bug. Any improvement is a great contribution!

Take a look at the tips for contributing, and make sure your code is well documented and follows best practice. COSIMA thanks you!

Synchronise your fork with upstream

Syncing frequently is a good way of avoiding conflicts when merging/pulling/pushing. You can do this by running the following in your gadi session:

git fetch upstream
git merge upstream/main

This grabs the latest changes in the upstream repository (COSIMA/cosima-recipes) and merges them into your main branch in your gadi clone. You can push these merge into your fork (origin) repository (your_user_name/cosima-recipes):

git push origin main

Create a branch

It is always good practice to create individual branches for each change/contribution you want to make. This will keep tidy and separated the work on different recipes and avoid the dreaded conflicts! In your gadi session run:

git checkout -b new_branch

Try to choose a self-explanatory name for the branch. For example relative_vorticity if you are working on a relative vorticity recipe.

Commit changes and push

Once you are done with whatever you wanted to accomplish, you can communicate this to the COSIMA/cosima-recipes repository.

1. Add and commit your changes:

git add path/notebook.ipynb
git commit -m "Brief description of what has been created or modified"

2. Push the changes you have committed to your origin repository (your_user_name/cosima-recipes):

git push --force origin new_branch

3. Now got to GitHub to your origin repository (your_user_name/cosima-recipes) and create a pull request to the upstream repository. You can do this by clicking on "Create pull request" button. Give it a self-explanatory title, a description and submit it. This will need to be reviewed before merging into COSIMA/cosima-recipes.
4. Optional step: if you have created this notebook in response to an Issue, you can link the Issue to the Pull Request using the Development tab on the right hand side. You can also nominate a reviewer!

Congratulations! You have contributed to the community, for which we are all grateful.

Getting your recipe through the review process

More often than never, the reviewer will suggest you make changes to your recipe before merging into COSIMA/cosima-recipes. You can continue working in your cloned repository in gadi, commit the changes and then push them to your fork following steps 1. and 2. above.

You don't need to create a new pull request. GitHub is smart and will update the original pull request with your changes!

Clean up

Once your contribution has been reviewed and approved, the pull request can be merged into the main branch of COSIMA/cosima-recipes. Once that is done, you may want to clean up the branch you worked from since it has become redundant. To do this, begin by syncing your main with upstream again:

git checkout main
git merge upstream/main
git push origin main

Then merge your main and your soon-to-be-forgotten branch:

git checkout new_branch
git merge main

Delete the branch and push the deletion:

git branch -d new_branch
git push origin --delete new_branch

Need help?

If you are getting error/conflict messages and need help working through these steps, remember your friendly ACCESS-Hive. Create a post and people will help you!