Intro to GitHub

QGreenland Researcher Workshop 2023

Intro to GitHub

  • Provide a “taste” of the utility of Git and GitHub
  • Intermediate/advanced topics out of scope

Working “in the open”

https://allisonhorst.com

Benefits of working in the open

  • Improve reproducibility with open data and open code
  • Increase innovation and quality through inclusivity
  • Facilitate global collaboration
  • Easier and more powerful if you are open from the beginning
  • Git/GitHub are not only for coders!

Git vs GitHub

Git logo

GitHub logo

Git

Git is the “foundation” of GitHub; it is an information (not code!) management system. Git can answer questions like:

  • Who made this change?
  • What did this information look like last week?
  • When did this change occur?
  • Why was this change made?

Learn more about Git

GitHub

GitHub is a hosting service for Git repositories with lots of extra bells and whistles. GitHub has competitors like GitLab and BitBucket which offer similar features, like:

  • Back up your work on their servers
  • Facilitating conversations and approval process for changes
  • Bug tracking and associated discussion
  • Documentation with Wiki-like features
  • Project management tools
  • Running automations in response to changes, e.g.:
    • Build a website and deploy it
    • Generate a PDF from LaTeX or Markdown
    • Check code for errors or style compliance
    • Compile code

Demo: Setting up a GitHub repository

Create a GitHub repository

New repository button at top-right of https://github.com

Get the “owner” right and make it public

Create a README file

Add README to an empty repository

GitHub README editor

To “save” the file, we have to click “Commit new file”. It’s helpful to write a change description, but in this case the default (Create README.md) is already descriptive enough.

Commit new file to the repository

Edit the README file

I made a mistake: I wanted the “Authors” to be on a separate line from “Selected dataset”.

README doesn’t look quite right, let’s edit it

I need to add a blank line between paragraphs, or Markdown will see them as a single paragraph:

README in the GitHub editor

This time, I’ll check my work:

Use the preview feature to validate this time

Now it’s time for a descriptive “commit message”!

Commit changes

Add a Jupyter Notebook

Download a notebook from JupyterLab

After selecting “Upload files”, you will be given the opportunity to browser your computer or drag-and-drop files into GitHub.

Upload a file to GitHub repository

After selecting “commit” on the previous page, your files are visible in the repository!

The notebook is now in your repository!

When you click to open your notebook, GitHub will display a rich preview!

View the notebook in GitHub

Review provenance

You can view the full provenance of your repository by selecting the “Commits” button.

Navigate to the commits view

Our commit messages tell a story about the history of the repository.

Commits are listed with newest at the top

Enable GitHub Discussions

GitHub repository settings

Scroll down until you see the “Features” section. From there, you can enable “Discussions”, “Issues”, and many other helpful features.

GitHub Repository > Settings > Features

Discussions navbar link is visible after enabling

Zenodo integration

Navigate to Zenodo’s GitHub settings

Scroll down until you find your repository

Note: You may need to configure your organization to enable third-party application access.

Enable the repository in Zenodo

On GitHub, create a release

Create a new release on GitHub

Input a title and “tag”

A tag is a unique string that we will use to identify the new release. GitHub makes useful suggestions on this page. A good first tag is v0.1.0.

Useful suggestions from GitHub on the right sidebar

Our first release

Our DOI in Zenodo! Click here to get a badge for our repo and copy the Markdown.

Paste the Markdown in our README.md file

Commit the change to the main branch

Our badge is looking fresh!

What next?

Exercise

💪 Working with a GitHub repository