0. Prerequisites to contributing

If you are new to COSIMA and have never used git/GitHub to collaborate and develop code, this is the place to start. Remember that the Github documentation already contains a lot of really useful information. Here we will outline the steps needed to get you up and running contributing to the cosima-recipes.

The recipes are meant to be worked on in NCI's gadi supercomputer. You will need to:

a. Create an NCI account

b. Connect to the necessary projects. This will usually be a project with computing time (ask your team leader/supervisor), and ik11, hh5, xp65 and cj50.

c. Be familiar with using ARE to open up a session with computing time.

Once you are up and running with gadi, you can go through the steps that follow.

1. Setting up your SSH keys

SSH keys to login to gadi from your local computer

You are probably going to work using gadi, and so you need to create your SSH keys to be able login from your local computer. Follow the steps here. This will allow you to login to gadi via a terminal without needing to fire up an ARE session that uses up computing resources.

SSH keys to link your repositories in gadi with GitHub

Setting up this SSH keys will allow you to clone, pull and push from your working repositories in gadi to a remote repository in GitHub. Login to gadi via the terminal and follow the steps outlined here. Remember to log in to gadi and don't do this from your local computer.

After you have generated the keys, add them to your GitHub account to start using them, following the steps outlined here

2. Creating your cosima-recipes fork

The best way to contribute to cosima-recipes is by "forking" the repository. When you create a fork, you are essentially creating your own repository from a copy of the O.G. at that point in time, so instead of working on COSIMA/cosima-recipes (which is the upstream repository) you will be working on your_github_user/cosima-recipes. The good thing is that you can still share code and be visible to the upstream repository.

Forking a repository is super easy. Just follow the steps outlined under the section Forking a repository but don't clone yet.

3. Cloning your fork in gadi

After creating your fork, you will want to clone it in gadi, which is where you will work from. Follow the steps in Cloning your forked repository but clone using the SSH link tab, not the HTTPS. This is very important.

4. Adding the upstream repository to your local clone

The last step before you are all set up to contribute is adding the upstream repository (remember this is COSIMA/cosima-recipes) in your gadi clone. To do this, run within your gadi clone:

git remote add upstream [email protected]:COSIMA/cosima-recipes.git

Check you are all good

• To check if your SSH keys in gadi are set up correctly, run

  ssh -T [email protected]

  from any gadi login-node session. If all is good you'll get the celebratory message

  Hi your_github_username! You've successfully authenticated, but GitHub does not provide shell access.

• From your gadi clone of the cosima-recipes directory, run git remote -v to see whether your origin (your GitHub fork) and upstream (the O.G. repository) are well configured. You should see this:

  git remote -v

  origin	[email protected]:your_user_name/cosima-recipes.git (fetch)
  origin	[email protected]:your_user_name/cosima-recipes.git (push)
  upstream	[email protected]:COSIMA/cosima-recipes.git (fetch)
  upstream	[email protected]:COSIMA/cosima-recipes.git (push)