What do we need to prepare for this session?

1. Sign up for a Github account;
2. (Optional) Github Desktop.

GitHub Organisation

• Collaborate with a team (or several teams) on a larger project with several repositories.

  • Great for big projects that involve several outputs or sub-projects, so everyone can see each others work without necessarily writing to the same repository
  • Teams can help to assign roles to groups of people, to keep everyone’s goals clear
  • Each team can have different access to certain repositories

  For example:

  • This SORTEE Hackathon: github.com/SORTEE-Github-Hackathon
  • Québec Centre for Biodiversity Science R Workshop Series: github.com/QCBSRworkshops
  • German Centre for Integrative Biodiversity Research (iDiv): github.com/idiv-biodiversity

Issues and pull-requests

Issues allow authors to get user/community feedback to keep their code or document(s) up to date with the literature, address issues, add features that other users want to use for their research.

• Issues are public (on a public repository), so these conversations are transparent.
• Issues also allow tracking of questions, bug reporting, suggestions and feature requests, which are often overlooked as contributions.
• You can also assign specific people to address issues as they arise, which helps to manage who works on what.

Pull requests allow for contributions from within the team or from other contributors (in a traceable way).

• Issues and pull requests are easily linked to each other (e.g. “This PR addresses #1”).
• Pull requests are checked before including the changes into the “main” version of the project, to avoid “breaking” things accidentally. You can assign certain people to validate pull requests before they can be merged into the project.
• This opens the door to external contributors, who can submit code (or writing).

Issues and pull-requests are at the heart of GitHub’s appeal for collaboration and open science.

For our workshop series, we use issues to invite feedback from our community, and to create open task lists for invited developers to address when they update workshop material.
For example: https://github.com/QCBSRworkshops/workshop08/issues.

Developers then make changes to the material, submit a pull request, which is then reviewed by the coordination team. This allows us to approve the changes, or give feedback to address any issues in the changes.
For example: https://github.com/QCBSRworkshops/workshop08/pull/9.

Issues and feature requests are often used in ecology and evolutionary biology research, in particular for packages. A few examples below:

• vegan
  
• EcoJulia
  
• Stanford CCB
  
• Atlas of Living Australia’s ALA4R
  
• Even GitHub uses this type of feedback github/feedback

Hands-on exercise (15 mins):

GitHub Insights

GitHub has several built-in display functions to track and see contributions from different users.

• Commits page
  • Covid-19 review
• Network graph
  • Covid-19 review
  • 10SR Git and GitHub

You can also find tools for automatically showcasing contributions

• all-contributors

Github Discussions (beta)

This is a new tool that is being introduced to GitHub, which is intended as a way to keep broader conversations open. For example, people can discuss a project at a conceptual level, have more in-depth discussions about what outputs mean (or don’t mean), and more. This is another way of tracking and showcasing contributions outside of code or writing, which are often left out because they happen in private email chains or are simply hard to keep track of.

You can take a peek on the Discussions tab for this repository. But, here are some examples of Github Discussions:

• Problems in how we use data/GIS
• Why SPEI?

Continuous Integration through GitHub Actions

Continuous integration (CI) is a practice where developers establish a consistent and automated way to build, package, and test applications and thus integrate their code changes early and often to the main branch or code repository.

Committing code more often detects errors sooner and reduces the amount of code a developer needs to debug when finding the source of an error.

Github Actions in a nutshell

Github Actions can help with task automation within your research development life cycle.

Its basic workflow is consisted of events that trigger jobs, which are sent to runners and have specific steps with actions it must complete.

Let us begin with the following example!

The instructions to run the above workflow is set in a .yaml file stored within the .github/workflow directory of your Github repository.

The YAML file for the above workflow can be written like this:

on: [push]

name: learn-github-actions

jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v2
        
      - name: Install node
        uses: actions/setup-node@v1
      
      - name: Install bats
        run: npm install -g bats
        
      - name: Run bats  
        run: bats -v

Specifically, the workflow can be detailed as:

1. name sections: which provide names to the entire workflow and its steps;

2. on: indicates the events that trigger this workflow. In this case, it will run whenever one pushes a commit to the repository;

3. jobs: defines the jobs that will be run when trigger by the on: event. In this case, check-bats-version (a user-defined name) runs-on the latest version of the Ubuntu OS;

4. steps: contains all actions that will be executed by the job. Our case contains four actions, two uses: predefined Github Actions, and two run:s commands that are executed directly in the OS terminal;

   1. The first step uses: the action hosted at actions/checkout on the branch or tag v2. This action allows one to check out the repository so the other actions can access and work at your repository. We can see more about this action here;
   2. The second uses: the action hosted at the actions/setup-node repository on the v1 branch or tag. This action installs and set up Node.js runtime environment within the runner;
   3. The third step run: a command that will install bats (which stands for Bash Automated Testing System);
   4. The final fourth step run: the command bats -v to check the version of bats.

We have stored this action within the .github/workflow directory of our Github repository.

Advanced examples

Markdown is a type of light-weight markup language, where instead of editing text with 
[**W**hat-**Y**ou-**S**ee-**I**s-**W**hat-**Y**ou-**G**et](https://en.wikipedia.org/wiki/WYSIWYG) 
software (e.g. Microsoft Word, Google Docs), we combine *data*, *code*, and
*narrative* in a single file and add formatting elements using plain-text. 

rmarkdown::render("dynamic_collaboration_material.Rmd")

Hands-on-exercise #2: Modifying a Github Action! (~10 mins)

It is fun-time #2!

We have compiled data on penguins inhabiting the Palmer archipelago (Antarctica) and we created this document (open it!) to report the results of our analysis!

Other tools

• fgbio: Tools for working with genomic and high throughput sequencing data
• Git Large File Storage (LFS)