Skip to content

Hosting experiment repository on Github: a workflow for users for publications.

Summary

These instructions are intended to help users share their experiments for publication in papers. They presume the user got started using the model following the "how to run a model" documentation.

Detailed instructions

These instructions

For example if one had followed, then

mkdir -p ~/access-om3
cd ~/access-om3
payu clone -b expt -B release-MC_25km_jra_ryf https://github.com/ACCESS-NRI/access-om3-configs 25km_jra_ryf
cd 25km_jra_ryf

In the example above, the payu clone command clones the latest release of the 25km repeat-year JRA55 MOM6 (M) CICE6 (C) configuration (-B release-MC_25km_jra_ryf) to a directory named 25km_jra_ryf and creates a new experiment branch (-b expt).

We then want to put the updated version of this experiment (with ther user's runlogs and configuration changes) onto their own github account.

Note

At this point in the instuctions, we are assuming changes have been made to the expt branch above. Typing git log should confirm this.

The below steps walks you through the steps to push your local Git repository to a new or different remote repository.

The first step is to add the New Remote, that is, your personal GitHub account. Use the git remote add command to add a new remote repository:

git remote add <new-remote-name> https://github.com/username/new-repo.git

username here needs to be your GitHub username.

Check that the new remote was added: 

git remote -v

Check the branch name used in the local repository (e.g. if you chose not to use the default above of expt): 

git branch 
> * <current-branch-name>
> other-branch-1
> other-branch-2

Push your branch (e.g., expt) to the new remote:

git push <new-remote-name> `expt`

Optionally, you might prefer to not push the expt name to the remote. For publication purposes you may wish to give it a more meaningful name (<preferred-new-name>). Push the experiment to this archive, assigning a branch name that matching the conventions: 

git push <new-remote-name> <current-branch-name>:<preferred-new-name>

Well done, your configuration and experiments should now be on GitHub. Most journals prefer for their to be a DOI or zenodo archive at this point.

To create that follow these steps:

  1. Navigate to the login page for Zenodo.
  2. Click Log in with GitHub.
  3. Review the information about access permissions, then click Authorize zenodo.
  4. Navigate to the Zenodo GitHub page.
  5. To the right of the name of the repository you want to archive, toggle the button to On.

Zenodo archives your repository and issues a new DOI each time you create a new GitHub release. Follow the steps at Managing releases in a repository to create a new one.