1 of 34

GitHub Clinic

Contributing from the browser

Champions Program

CC By Openscapes

Artwork by Allison Horst

Last updated 2022-10-21; deprecated. Current version

1

2 of 34

Today’s Goals

Growth Mindset & motivation for GitHub

Powerful way to contribute & collaborate across responsibilities

Explore GitHub as a tool beyond code and archiving (together)

GitHub commits to contribute and publish
GitHub Issues for project management

Practice GitHub from the browser (breakout rooms)
Today’s Clinic: designed for everyone across levels to learn and help each other

2

3 of 34

We won’t cover local git/GitHub setup/workflows today.

Excellent resources to learn more:

Excuse me, do you have a moment to talk about version control? (Bryan)

Humorous, honest discussion paper re: GitHub value (American Statistician & PeerJ)

Git for Humans (Bartlett)

Nice intro of GitHub for non-coders (video)

Happy Git with R (Bryan)

Friendly resource for git/GitHub theory, commands, workflows, troubleshooting. R/Studio focused but relevant far beyond.

R for Excel Users workshop (Lowndes & Horst)

Collaborative R/RStudio + GitHub workflows with environmental data (LTER)

3

4 of 34

Growth Mindset

The power of yet:

you develop abilities through practice

Compared to a

fixed mindset, where abilities are static

Important mindset for working with Future You and Future Us
We can bring this thinking to GitHub

Research by Carol Dweck (book, TED Talk; video)

Illustrations from “GitHub for supporting, contributing, and failing safely”

(Horst & Lowndes 2022)"

5 of 34

“Collaboration is the most compelling reason to manage a project with Git and GitHub”

(Bryan 2017, PeerJ, “Excuse Me, Do You Have a Moment to Talk About Version Control”)

Future You, Future Us
Across computers/devices
Active makers, readers, reviewers

–> To introduce GitHub, we can use the idea of climbing

5

6 of 34

6

7 of 34

7

GitHub “commits” help us focus on the work, not the bookkeeping

It takes care of otherwise time-consuming versioning and unrelenting file tracking.

8 of 34

8

GitHub “Issues” helps us support others and existing work

It helps us with organizing, improving documentation, asking and answering questions - critical to all projects whether we’re writing code or not.

9 of 34

What is GitHub? – traditional answer

GitHub is a company - an online collaborative platform. It is built on top of Git - software that does file versioning and bookkeeping.
You can think of GitHub working like Dropbox - but with more control.

9

Stef notes�GitLab and Bitbucket are other platforms analogous to GitHub, build on top of Git

Git and GitHub’s job is to know and show you that yes, you did make a change and you saved it. GitHub lets you say hello to a single file, who edited it, when

https://afredston.github.io/learn-git/learn-git.html#1_Introduction

Past speaker notes from transcript: The main question is what is git and github just to start. And so, git is powerful version control software for your local computer, and it helps you get away from you, copying the same file over and over and annotating something about it like the date or who commented or whatever.  So it helps you get away from this idea of like an our scripts final final final.  And because it's sorry and so I'll, I'll complete this slide five and show like instead you'll just have a single file and gitHub it's like tracking. What start get is tracking what's going on, find you, through time.

10 of 34

What is GitHub? – nontraditional answer

Publishing platform. A new way for sharing & communication - your files can become websites! Share the url once, it’s always the latest version.

Project management system. Short- and long-term collaborative “todo” lists

“Issues” & “Projects”

10

Annual reports

Shared todo’s

Sharing your GitHub files as websites lets you participate in open science in a new way.

Past speaker notes from transcript: So that's kind of the traditional answer of what is gitHub, but if we move on to slide eight. non traditional answer is that it is this really powerful publishing platform. And it's an amazing project management system. So, it's a publishing platform for Single files that you can that can display as HTML, but it can also combine, you can combine single files into Ebooks or websites or slides are interactive dashboard and so you know that's that's still a blog down and everything. We were thinking about with our markdown GitHub lets you publish that really easily.  then it's also really powerful as this project management system so you can use GitHub issues as ways to have conversations and track progress on projects, they don't need to be Code oriented. And then you can combine issues on the project boards and have like one class and conversations that are easier to onboard new team members to because they're not like buried in emails or whatnot.

11 of 34

GitHub framework in a nutshell

Repositories (“repos”) - main unit, a folder

Contained, with permissions
Public or private

Users vs. Organizations

EmilyMarkowitz-NOAA vs.

nmfs-openscapes

Commits & Issues

The way you contribute

through GitHub

Let’s explore a repo and commit a change →

11

Above, NMFS-Openscapes is the organization with the 2022-noaa-afsc-fall repository. This repo has 2 files. The most recent commit was made by EmilyMarkowitz-NOAA (a user) 11 days ago: they updated the README.md file.

repo

org

repo

Stef notes

Let’s set aside analogies and dig into the GitHub framework in a nutshell

Where that repo lives is in an individual user account, or in an organization account.

… Let’s explore a repo together and see what the workflow is like to commit a change.

Past speaker notes from transcript: the GitHub framework in a nutshell, is that there are users and organizations that you can be a part of an open skin a GitHub. So my username is Jules 32, and I'm part of the openscapes organization so this is kind of set up the way  a lot of like social media things are set up like if you think of like a Facebook account or a group or something like that you can kind of think about that that in the main unit of GitHub as a repository. And that is a contained thing that you can have specific permissions for, so you can have some repositories that are public available to anyone you can have some that are private that you have edit access or So you know, you can you can do a lot of different things of the sort of unit of the repository.  And the way you contribute to things in that repository, or through commits and writing those little short commit messages so I know you're both familiar with that but that's, You know when you create a snapshot of like you've saved your files if you  worked like normally but like if you're going to commit something this is like a period of time that you're trying to capture for later on.  This idea of like using a get commit is like using anchors if you're a climber, because you can only fall as hard as you as your last commit.

happy get with our is, I think, the best resource for learning, get or GitHub. It's our focus but it's also just has like a lot of theory and good advice.  That's not specific to our so I definitely recommend that to everybody and their troubleshoot the troubleshooting, chapter, which is called like GitHub hell. It's like, where to send you know the first place to look if you're ever having issues or anyone who knows having issues.

12 of 34

GitHub repo

orientation

(demo)

Let’s explore a repo: ggplot2.

Every GitHub repo looks the same.

First things to look for in red:

12

URL (changes as you navigate)

[user or org] / repo (doesn’t change)

Files and folders

Recent activity?

website

Scroll down for README

Every GitHub repo looks essentially the same

Org
Repo
See URL
Folders
README displayed by default

Having a README file has become so customary on GitHub that it is displayed by default and serves as a kind of homepage. If the repo is for software, the README typically will say briefly what it does, how to install it, and then other info on usage. This example is for a popular and powerful visualization pkg in R. And it’s all on GitHub!

Click website
Recent activity?

Past speaker notes from transcript: Palmer penguins was created by Openscapes Champion Allison Horst as an alternative to the default `iris`, which has racist origins. It uses real data from the LTER. It is in the process of being built into base R! https://twitter.com/juliesquid/status/1287852937239126016

A lot of this is familiar to both of you already but also not everything there's new stuff all the times or, you know, you can also think about like how we kind of teach and walk through this. and whether it be like what you might do differently or. Similarly, so okay so I'm going to open this repository, and we can just look at sort of to get oriented to a GitHub page. 

The first thing I like to note is that the, this is always going to be the USername or the organization and then this is the repository.  And this kind of look is the way any repository will look.

So they'll be these tabs up here that will look at in a moment. The main kind of meat of the repository or all the files in it, that are always visible from this main page.

And my, you can note, notice to that this URL up at the top here github.com is then going to be the username and the repository name which currently matches this as well.

So when I first look at a repository. One of the first things I look at is how recently it's been updated to see, like if this is something that you might want to. You have to this thing is maintained or or whatnot. But yeah, there's files here, most recent time their name, let me see what else I wanted to point out here. Recent Activity.

Repositories will also have a readme it. This is convention, they don't, you don't have to have a readme but it's conventional to have a read me document and your top level of your repository to say like what is this repository where you've come to. And there's often installation instructions and how to get help. This is, you know, kind of this practice in the open source community so that people can get Oriented and so that's that's a good, good thing to look for when you first come to a repository that might not be familiar with. And then there's also a way to link to a website that might exist from that repository and the GitHub and are, and now Python is making it a lot easier to have websites to describe your code so that this GitHub repo is not your only landing page but so  this is an example of where this would take you. 

This is an example of where this would take you, is to like a website about this code that's made with our that's published with GitHub, so it's all kind of already interlaced and there's like nice stuff that's coming out all the time. Okay, so that's that's what a repository looks like every GitHub repository will have that same view. 

13 of 34

Let’s edit files from GitHub (demo)

In our Cohort repo

Note: editing from the browser is limiting – your main workflow will be to sync the repo to your local computer. However, you will sometimes edit in the browser, and it’s a no-install-required way to onboard new people to GitHub

13

Click pencil to edit

Write! Supports Markdown formatting

Scroll down to commit!

Markdown is a formatting language with only about 15 rules. Notice syntax for # headers and *italics*

(see cheatsheet)

Stef notes

Now let’s look at the repo for this Cohort. I’ll orient you briefly, demonstrate, then give you a task to try in breakout rooms

Org
Repo
Github-clinic folder has a file for each person.md. Ssee URL change: this is a way you can share a specific file with someone by sharing its URL
Click _demo.md; the file gives you instructions on what to do; highlight each line as you execute

“write as I go”
commit msg - write a msg to remind myself what I did

note my commit in repo page

Past speaker notes from transcript: I'll demo what we'll do, and then we'll let you both to try this too. 

Let's see. This is our GitHub clinic repository that will practice on for right now and I, I didn't make you both editors of this repository Did you get that.

So, you'll see that. See, when you open a file will just open this read me.

When you click on a file. You'll see that, you know, the username organization stays the same, the GitHub repo stays the same up here this top level but now here, like tells me where I am in my file path.

And you'll see to that the URL changes. So you can. It's, it's nice because even though there's, you know some, in this case something additional here called blob main telling me which branch I’m in.For the most part, that URL matches, you know this the final class you're able to navigate nicely. 

And so you can edit files from the browser, by clicking this little pencil. And so when I click this little pencil. I can add edits here, list items by adding a dash, i can make things bold this markdown syntax and I can sort of preview what I've done here by clicking preview so this is still in the editor pain and gitHub, but it's like a sort of see this, I can also look at differences if I wanted to and see like what I added versus deleted . to this file but then to save it, I would drive, I would scroll down here and see this commit changes, where there will be a default message that will just say update readme, but I could say like, I added a list. 

14 of 34

Your turn: practice editing & committing

Goals: practice committing work in GitHub

Go to our repo and find yourname.md
Click on the pencil to edit your file
Practice small edits & commits with commit messages

Github.com has a default message, but get into the habit of writing an actual message to yourself/others (breadcrumbs)
If it asks you to propose changes rather than committing, check your email to accept the invite to collaborate in this repo

Also try: upload a file via drag-and-drop (it will be public!)
Have fun! Talk to your breakout group, share what you learn

14

15 of 34

Review together after breakout rooms (demo)

You’ve been collaborating on GitHub! Look at the commits:

15

Stef notes

Refresh Cohort repo page
Note number of commits; click and note a couple
Click SHA to see commit details; note red and green show exact changes
Looking at a commit, note alphanumeric tag & it shows in URL; go back in time to see whole repo in past

Past speaker notes from transcript: I will bring you back from the breakout groups, and will pretend that we debriefed a little bit.  comments, anybody? I love it. It's great.

I'm doing this, participating in this particular exercise was just to get comfortable with commit messages and markdown at first, or like also showing like every repo should have a readme and this is how you can you read me. That's a very good question because it's not. Yeah, it's not, we're showing a lot of things, but we're not clear on what the actual learning goals are. So I think the main ideas.  Our to familiarize you to what a repo it looks like and how you navigate through it, how you can edit files from the browser, and that that comes through as a commit message. And so yeah there is some, there is markdown in there and maybe.  Maybe it's less important that we, I don't know. 

So, now we can look at this commit history again together and see that we've all just been collaborating on GitHub together, we've had different commits from Korea Julian anna and if I we can see that like people are contributing and like GitHub is doing its job to, you know, Blend these edits together.  In this situation, you were all just working on specific files but GitHub also has this ability to to weave lines within a file together.

And you can use this history, there's a bunch of different places you can view the repository, but you could go back to this moment in time. 

You can then see how that changes when Corey adds these certain lines and so you kind of see this red and green.

You're always there when you're in, when you're looking at a certain commit.

You're also able to like view just the, the file at that moment without any edits. So there's some, you know, if you're trying to demonstrate with a collaborator about something or some real several different views. 

Yeah, so I'll just leave it at that for now, but keep an eye on how the URLs change as you're looking at different versions because that's a way that GitHub is tracking that specific moment in time when you committed that file at that moment. 

16 of 34

Good project management

Using project management software -

a strategy used by software developers

and people working on projects with many moving parts

Organize and track projects with single or multiple & overlapping users
Streamline technical discussions for people with different responsibilities
Key for onboarding Future You and Future Us
GitHub Issues let you discuss/organize in the same place as your code

16

17 of 34

GitHub Issues in the wild

17

Open software peer review

Bug reports, code, feature, & help requests

Event crowdsourcing and planning

“traditional” and “less traditional”

🎉

18 of 34

Explore GitHub Issues (demo)

Let’s go to our Cohort’s repository > Issues

18

Let’s see what Issues look like & then we’ll practice these together.�Cohort repos:�https://github.com/nmfs-openscapes/2022-noaa-sefsc-fall

https://github.com/nmfs-openscapes/2022-noaa-swfsc-pifsc-fall

https://github.com/nmfs-openscapes/2022-noaa-afsc-fall

https://github.com/nmfs-openscapes/2022-noaa-nwfsc-fall

Stef notes

We’ve been in the code tab so far; there are others you can explore

Call 1 Digest > emoji

New issue “A question about the data” > tag Ileana > use Markdown - a formatting language with only about 15 rules > numbered list, checklist, heading, preview > assign, label > submit > see URL > comment > close as completed > back to main Issues view

Your turn :-)

Notice Markdown syntax for # headers and *italics* (cheatsheet)

Link to a specific line of code ex: https://github.com/amfriesz/lpdaac_hls_tutorial/blob/main/environment.yml#L30

See other repo with issues: https://github.com/NASA-Openscapes/earthdata-cloud-cookbook

19 of 34

Your turn: practice creating & commenting on issues

Goals: practice using Issues for collaboration, Markdown practice

Go to our cohort repo’s Issues
Create an Issue, tag people in your breakout group (ask their usernames)
Browse issues, comment in other issues. Try:

Practicing Markdown
Creating a label and applying it, assigning people
Adding issues to a Project (create one if need be)
Closing an Issue

Have fun! Talk to your breakout group, share what you learn

19

20 of 34

Regroup

Here’s what your inbox will look like afterwards:

20

This is pretty rare to receive so many Issues emails all at once.

But you can switch your setting so that you only receive emails about Issues that you are tagged in. Click on Watch in the top right:

21 of 34

GitHub Organizations & Projects examples:

21

https://github.com/orgs/Openscapes/projects/5

Project Boards for Issues (kanban board)

Project has a mix of public & private Issues

https://github.com/nmfs-opensci

https://github.com/nmfs-openscapes

Organizations for skillsharing and teaching

22 of 34

GitHub has a built-in viewer

https://github.com/openscapes/2021-sasi <> https://openscapes.github.io/2021-sasi

22

23 of 34

View your repo as a website!

username.github.io/reponame/

nmfs-openscapes/2022-noaa-nwfsc-fall/github-clinic/yourfile

404 error? Remove trailing / from the url
Wants you to download? Remove trailing .md from the url
This worked because of repo’s settings: GitHub Pages

Settings > Pages > Source > Branch: main, /(root)

23

24 of 34

Extra slides

24

25 of 34

GitHub Issues in the wild

25

Private conversations and archiving

Bug reports, code, feature, & help requests

Event submissions and coordination

“traditional” and “less traditional”

26 of 34

Explore GitHub Issues (demo)

Let’s go to our Cohort’s repository > Issues

26

27 of 34

Strategies for Issues

Every repo has issues, but do you want to use issues in every repo? Consider the purpose:

“Traditional” bug/features for code: keep it public within that repo
“Non-traditional” lab & science conversations: make private, think ahead: will the code/contents of that repo be made public in the future?

OHI thought process & strategy:

Although we have many repos, we didn’t want to have to search across repos to find a conversation (although now GH can search across Organizations!)
We also wanted our repos to be public, but to have private conversations
So we created a single private repo called “issues” that we only use for issues.

27

28 of 34

28

So far, we’ve been working on GitHub.com, where we contribute changes through commits

Frazier 2016

When we work elsewhere, to contribute we stage, commit then push back to GitHub.com

Stage and Commit your changes after saving

*

*(or JupyterHub)

To get our work elsewhere we clone the first time and thereafter pull any updates from GitHub.com

Pull, commit, push together is called syncing

29 of 34

GitHub syncing

29

To contribute back to GitHub.com from your local or cloud setup:

Frazier 2016

30 of 34

30

Jenny Bryan, Code Smells and Feels

31 of 34

GitHub is collaborative software designed to organize interrelated files and to track changes by potentially different people through time - not limited to code.

31

Illustrations from “GitHub for supporting, contributing, and failing safely”

(Horst & Lowndes 2022)"

32 of 34

32

GitHub helps us reuse

GitHub helps us reuse existing work, which lets us learn and build from other people’s shared experience rather than reinventing on our own.

GitHub helps us fail safely

Because we can return to previous versions easily, painful consequences of failing are reduced. We can more bravely try things and start making contributions.

33 of 34

GitHub repo

orientation

(demo)

Let’s go to our cohort repo.

Every GitHub repo looks the same.

Here’s the first things to look for:

33

URL (changes as you navigate)

[user or org] / repo (doesn’t change)

Files and folders

Recent activity?

website

Scroll down for README

Palmer penguins was created by Openscapes Champion Allison Horst as an alternative to the default `iris`, which has racist origins. It uses real data from the LTER. It is in the process of being built into base R! https://twitter.com/juliesquid/status/1287852937239126016

A lot of this is familiar to both of you already but also not everything there's new stuff all the times or, you know, you can also think about like how we kind of teach and walk through this. and whether it be like what you might do differently or. Similarly, so okay so I'm going to open this repository, and we can just look at sort of to get oriented to a GitHub page. 

The first thing I like to note is that the, this is always going to be the USername or the organization and then this is the repository.  And this kind of look is the way any repository will look.

So they'll be these tabs up here that will look at in a moment. The main kind of meat of the repository or all the files in it, that are always visible from this main page.

And my, you can note, notice to that this URL up at the top here github.com is then going to be the username and the repository name which currently matches this as well.

So when I first look at a repository. One of the first things I look at is how recently it's been updated to see, like if this is something that you might want to. You have to this thing is maintained or or whatnot. But yeah, there's files here, most recent time their name, let me see what else I wanted to point out here. Recent Activity.

Repositories will also have a readme it. This is convention, they don't, you don't have to have a readme but it's conventional to have a read me document and your top level of your repository to say like what is this repository where you've come to. And there's often installation instructions and how to get help. This is, you know, kind of this practice in the open source community so that people can get Oriented and so that's that's a good, good thing to look for when you first come to a repository that might not be familiar with. And then there's also a way to link to a website that might exist from that repository and the GitHub and are, and now Python is making it a lot easier to have websites to describe your code so that this GitHub repo is not your only landing page but so  this is an example of where this would take you. 

This is an example of where this would take you, is to like a website about this code that's made with our that's published with GitHub, so it's all kind of already interlaced and there's like nice stuff that's coming out all the time. Okay, so that's that's what a repository looks like every GitHub repository will have that same view. 

34 of 34

GitHub repos & issues examples

34

https://github.com/pinskylab

https://github.com/Froehlich-Lab/anti-racism

github.com/Openscapes/teaching-learning-resources/issues

Shared, running list of resources we find useful

the GitHub framework in a nutshell, is that there are users and organizations that you can be a part of an open skin a GitHub. So my username is Jules 32, and I'm part of the openscapes organization so this is kind of set up the way  a lot of like social media things are set up like if you think of like a Facebook account or a group or something like that you can kind of think about that that in the main unit of GitHub as a repository. And that is a contained thing that you can have specific permissions for, so you can have some repositories that are public available to anyone you can have some that are private that you have edit access or So you know, you can you can do a lot of different things of the sort of unit of the repository.  And the way you contribute to things in that repository, or through commits and writing those little short commit messages so I know you're both familiar with that but that's, You know when you create a snapshot of like you've saved your files if you  worked like normally but like if you're going to commit something this is like a period of time that you're trying to capture for later on.  This idea of like using a get commit is like using anchors if you're a climber, because you can only fall as hard as you as your last commit.

happy get with our is, I think, the best resource for learning, get or GitHub. It's our focus but it's also just has like a lot of theory and good advice.  That's not specific to our so I definitely recommend that to everybody and their troubleshoot the troubleshooting, chapter, which is called like GitHub hell. It's like, where to send you know the first place to look if you're ever having issues or anyone who knows having issues.