Practical: GitHub & Rstudio for collaborative coding

EvoLottery

Welcome to the evolutionary lottery of skull and beak morphology


Beak and skull shapes in birds of prey (“raptors”) are strongly coupled and largely controlled by size.

  • In this exercise, each participant will fork a GitHub repo, and contribute a file required to simulate the evolutionary trajectory of an imaginary species’ body size.

  • We’ll use GitHub to collate all species files and plot them all up together at the end! We’ll also discover the skull and beak shapes associated with each simulated species size.

Start!

Clone Github repo

Fork it

make your own copy of the repository on GitHub. Fork are linked and traceable

GitHub makes a copy into your account


🚦 Clone repo

copy repo link to create a new Rstudio project from the repository.

Create new project in Rstudio

Checkout from version control repository

Clone project from a git repository

Paste repo link copied from GitHub into Repository URL field. Click Create Project.

Rstudio project now contains all files from the GitHub repo.

Make a change to the repo

make a copy of params_tmpl.R

open params/params_tmpl.R

SAVE AS NEW .R script in params/ folder

Use species name of your choice to name new file.

Please DO NOT OVERWRITE params/params_tmpl.R.

Edit file

Edit file with parameters of your choice and save.

The parameters each participants need to supply are:

  • sig2: A numeric value greater than 0 but smaller than 5

  • species.name: a character string e.g. "anas_krystallinus". Try to create a species name out of your name!

  • color: a character string e.g. "red", "#FFFFFF" (Check out list of colours in R)

NB: remember to save the changes to your file

Commit changes locally to git

In the git tab, select the new file you created and click Commit.

Please ONLY COMMIT YOUR NEW FILE

Write an informative commit message and click Commit

your new file has now been commited

Push changes to GitHub

on the git tab click ⇧ to push changes to GitHub

changes have now been updated in the GitHub repo

Create pull request

In your repository, create new pull request to merge fork to master repo (ie the original repo you forked)

GitHub checks whether your requested merge creates any coflicts. If all is good, click on Create pull request

Write an informative message explaining your changes to the master repo administrators. Click on Create pull request

The repository owner will then review your PR and either merge it in or respond with some guidance if they spot a problem.

Check original repo to see your merged changes

We’ll merge all contributions and plot them together at the end!

Now that everyone has contributed to the RSE-Sheffield repository (the upstream repository), the params/ folder contains a number of files, one for each successful pull request.

However your local copy of the repository only contains the template and your own file.

Q: How can I merge changes from the upstream repository to my local repository?

Add upstream remote

Check current remotes

We can check the urls of remotes currently linked to our local repo using usethis::git_remotes().

usethis::git_remotes()
$origin
[1] "https://github.com/annakrystalli/collaborative_github_exercise.git"

We see that only my form is currently listed as a remote under the name origin.

Add the RSE-Sheffield repo as upstream

To add a new remote we need the https url of the upstream repo (the equivalent of the one we used to create our project from our fork through version control) which in this case is https://github.com/RSE-Sheffield/collaborative_github_exercise.git.

We can then use usethis::use_git_remote() to set the upstream repository:

usethis::use_git_remote(
    name = "upstream", 
    url = "https://github.com/RSE-Sheffield/collaborative_github_exercise.git")

We can check that everything was set correctly with usethis::git_remotes()

usethis::git_remotes()
$origin
[1] "https://github.com/annakrystalli/collaborative_github_exercise.git"

$upstream
[1] "https://github.com/RSE-Sheffield/collaborative_github_exercise.git"

Synch with upstream

Finally, to synch with the upstream repository we can now use function usethis::pr_pull_upstream(). This fetches the master branch from the upstream repository and merges it into our own local master branch.

usethis::pr_pull_upstream()
✓ Pulling changes from GitHub source repo 'upstream/master'

You should now have all participant files in the params/ folder and will be able to generate all bird skulls if you run plot_trait_evolution.Rmd locally.

Synch origin

To also synch your origin remote repository you can simply push the merged upstream changes up to GitHub.