Skip to main content

WEEL Guide

23 Sharing Projects

This is a small portion of the larger discussion surrounding reproducible research: sharing manuscripts and code. Here, I’ll outline some steps for turning a repository into a clean, public facing resource accompanying a paper or project.

23.1 Examples

In our lab:

  • the SocCaribou repository is a fully functioning R package with functions used for the paper, and a series of ordered scripts for running the analysis. The paper included is simply the journal’s typeset version.

  • the spatsoc-application-paper. This is a paper outlining the R package spatsoc developed by Alec, Quinn and Eric. Included are the scripts to generate each of the figures, the data used for the figures, and the full .Rmd manuscript, along with a typeset vesion.

  • the MovingAcrossGradients lab paper from 2018.

Each of these repositories are also linked to Zenodo, with “GitHub releases” triggering an updated DOI, etc.

A couple examples from outside our group include Carl Boettiger’s nonparametric bayes and noise phenomena papers.

23.2 Moving from GitLab to GitHub

Three options and it depends on if you’d like your repository to be mirrored over (dynamic, with updates) or imported (static, one time snapshot). Using the GitHub Importer (option 3) is easy but will only take a static snapshot. Otherwise, change your remote (option 1), or use an access token (option 2) and mirror the repository for a dynamic link between GitLab and GitHub that will copy over future changes.

23.2.1 Option 1: Changing your remote (dynamic)

Note: This approach locally changes your remote path to the Git repository. If there are multiple users of the repository, they must either 1) also change their remote path or 2) clone the new repository at the updated path ( and ideally delete the old local repository).

On GitHub.com:

  1. Make an empty repo (https://github.com/new). Don’t select “initialize with a README” - you want an empty repository.

In GitAhead, or other Git tool on your computer:

  1. Open the repository you want to move to GitHub.

  2. Edit the URL of the remote. In GitAhead: Select the “Remote” menu/Select “Configure remotes”/Double click on the URL and change the value to your GitHub clone URL eg. https://github.com/wildlifeevoeco/MovingAcrossGradients.git or :wildlifeevoeco/MovingAcrossGradients.git

  3. Push. It may take longer than usual, it is going to push the entire Git history to the empty GitHub repository.

  4. Check your new GitHub repository. You should see all the commits and files there.

If you want your GitLab version to stay up to date, use a Pull remote mirroring. More information here: https://docs.gitlab.com/ee/user/project/repository/mirror/pull.html

23.2.2 Option 2: Using an access token (dynamic)

On GitHub.com:

  1. Make an empty repo to receive commits from GitLab (https://github.com/new). Don’t select “initialize with a README” - you want an empty repository.

  2. Generate a new personal access token at https://github.com/settings/tokens

    • Select public_repo

  3. Copy it, to use as password on Gitlab.com below

On GitLab.com:

  1. Navigate to “Settings/Repository” (https://gitlab.com/user/repository/-/settings/repository)
  2. Select “Mirror a repository”
  3. Mirror direction: Push
  4. Repository URL: https://<your_github_username>@github.com/<your_github_group>/<your_github_project>.git
  5. Password: paste the personal access token generated on Github here

Check results:

  1. Wait for the spinning circle to finish, make sure no errors come up.
  2. Navigate to your new GitHub repository. It may take a few minutes to update.

23.2.3 Option 3: Using GitHub Importer (static)

  1. Open https://github.com/new/import.
  2. Select the “Owner”. Note: you can select the wildlifeevoeco as “Owner” if this is a lab paper/project. If you don’t see that as an option, ask Alec to add you as a member of that group.
  3. Provide a repository name.
  4. Select “Public”.
  5. Select “Begin import”
  6. If prompted for credentials, provide them for the repository that is being imported, not GitHub.
  7. Check your email for confirmation.

The GitHub Importer is described here.

23.3 Linking Zenodo and GitHub

  1. Set up your repository in the standard way with folders for data, scripts, manuscript, etc. See here for details.

  2. Host your repository on GitHub. Note: you can select the wildlifeevoeco as “Owner” if this is a lab paper/project. If you don’t see that as an option, ask Alec to add you as a member of that group.

    • making a new repository on GitHub and pushing there. or by
    • mirroring your existing repository from GitLab there. See below or here for extended details.

  3. Create a Zenodo account, log in, link to GitHub, and turn on the repository of interest*. Here are all the details.

  4. Create your release (see here for picking a version number), get a DOI, add it to your README with the badge shown in here.

  5. Edit the page on Zenodo, setting up manuscript/project authors, title etc.

* Note: make sure to turn on the repository of interest, before making the release on GitHub. At the moment, Zenodo only tracks future releases - though in progress here.

* Note: if you need to make changes after publishing, make those changes in the repository and add a new Git tag + release on GitHub (https://github.com/namespace/repo-name/releases).

23.4 Preserving Zenodo edits across releases

If you re-release your Github repository, the new Zenodo record will lose all the details, like authors, ORCIDs, descriptions, etc.

A solution is to use a special file (.zenodo.json), and save it in your repository.

Two options for making this file:

  1. Manually write it (careful for syntax errors), for example:
{
  "description": "<p>This repository contains the code accompanying the paper &ldquo;At a snail&rsquo;s pace: the influence of habitat disturbance on terrestrial snail movement using experimentally manipulated mesocosms&rdquo;.</p>\n\n<p>This project depends on some incredible R packages. We use <a href=\"https://github.com/ropensci/targets\"><code>targets</code></a> for declaring the workflow and <a href=\"https://github.com/rstudio/renv\"><code>renv</code></a> for a reproducible environment. General processing uses <a href=\"https://github.com/Rdatatable/data.table\"><code>data.table</code></a> and plotting with <a href=\"https://github.com/tidyverse/ggplot2\"><code>ggplot2</code></a> and <a href=\"https://github.com/thomasp85/patchwork\"><code>patchwork</code></a>. iSSA methods with <a href=\"https://github.com/jmsigner/amt\"><code>amt</code></a>, <code>raster</code> and <code>sf</code>, modeling with <a href=\"https://github.com/glmmTMB/glmmTMB/\"><code>glmmTMB</code></a> and <code>lme4</code>.</p>", 
  "title": "Code accompanying - At a snail's pace: the influence of habitat disturbance on terrestrial snail movement using experimentally manipulated mesocosms", 
  "creators": [
    {
      "affiliation": "Memorial University", 
      "name": "Emily Denief"
    }, 
    {
      "orcid": "0000-0001-5449-5449", 
      "affiliation": "Memorial University", 
      "name": "Julie W. Turner"
    }, 
    {
      "orcid": "0000-0002-5622-4973", 
      "affiliation": "Memorial University", 
      "name": "Christina M. Prokopenko"
    }, 
    {
      "orcid": "0000-0002-4706-1762", 
      "affiliation": "Memorial University", 
      "name": "Alec L. Robitaille"
    }, 
    {
      "orcid": "0000-0002-8534-4317", 
      "affiliation": "Memorial University", 
      "name": "Eric Vander Wal"
    }
  ]
}
  1. Generate one on Zenodo after you edit the record, then save it in the repository
    1. Open your Zenodo record (eg. following the link in the badge)
    2. Edit the record (top left, orange button)
    3. Save the record
    4. Export the record as a JSON (bottom of the page)
    5. Grab the metadata chunk within this exported JSON (edit it so it looks like the above example)

23.5 Resources

A recent community call with rOpenSci: summary blog and notes.

A paper on research compendium from Lincoln Mullen and Carl Boettiger.

Details in the GitLab docs on mirroring