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
  • See continued learning page
  • Attend office hours!

We love Git and are excited to teach about it, but we don’t have room in this workshop to fit that and still meet our other goals. We welcome anyone who wants to learn more to attend office hours on day 4. We also provide resources for continued independent learning.

Working “in the open”

https://allisonhorst.com

Benefits of working in the open

• Improve reproducibility with open data and open code
  • ‼️ Zenodo integrates with GitHub for auto-generating DOIs
• 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!

Open Science principles can apply to all of the work that you are doing. Now that we have some knowledge about the data that we want to keep track of and share with others, let’s utilize GitHub as the mechanism to translate that knowledge to documentation.

Git/GitHub are not only for coders! You can open your manuscripts, your books, your websites, your methodology, and your documentation using these tools.

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

Git is the underlying technology that makes GitHub work. Git manages information over time, enabling collaboration and “time travel” through the history of your work products.

There are alternatives to Git, like Mercurial and SVN, but Git is the most widely adopted information management tool.

At its core, Git is a command-line interface, but there are so many interfaces built on top of it to make it more powerful and/or user-friendly. There are editor integrations for VIM, Emacs, Visual Studio Code; there are websites built on top of it, like GitHub, BitBucket, GitLab.

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

We are focusing on GitHub instead of its competitors because it is currently the most popular. If you are interested in an alternative which is more open, consider looking into GitLab, which offers an open-source core called “Community Edition” and a source-available “Enterprise Edition” which provides extra features.

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

The first line is the “subject” of the commit message, and the large text box is the “body” of the commit message. Write a descriptive summary for the subject, and if necessary, populate details in the body. This will build a rich and readable provenance for your repository.

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 and issues are closely related; discussions are focused around community engagement, and issues are focused around project management. A discussion can be converted to an issue and vice versa. We recommend using both!

Discussions navbar link is visible after enabling

Zenodo integration

• Visit https://zenodo.org
• “Log in with GitHub”

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?

• Add a CITATION.cff file to the repository to help Zenodo generate a better citation.
• Create a CHANGELOG.md file and update it with every release.
• Consider other “badges” you can add, e.g. NSF award badge.
• Consider using GitHub Projects and GitHub Issues to enable community involvement and awareness from the beginning.

Exercise

💪 Working with a GitHub repository