Github 101

The 15-minute version

​

This is going to be extremely compressed.

Maybe schedule a time to work through the longer version with your peers?

1

Assumptions of this workshop:

• You already have a Github account (even if it’s new for you)
• You’re already a part of the EDGI EEW Github team
• You’re a pretty quick learner who will do ask questions on #stupid_questions when this workshop inevitably does not answer all your questions
• Everybody here has something to learn & something to teach; you’ll look things up and help each other out
• If there’s something you really want to learn about, you’ll ask for a tutorial! [Kelsey note: I am explicitly offering to teach you any tool you’d like, please hit me up and ideally bring some peers with you]

2

This workshop will...

Cover:

• Some terminology related to all of this stuff
• How to edit a file
• The Markdown language: how to make a table
• How to review a pull request

Not cover:

• Issues
• Etiquette beyond: communicate a lot! (Later, read slides headed “Open Source Culture Note”)
• How to create new files
• How to make & use milestones, labels, project boards
• Merge conflict resolution

​

3

You’re going to add yourself to the readme!

go to https://github.com/edgi-govdata-archiving/EEW_Planning

4

5

organization name

repo (“repository” of files) name

README is a special file that displays automatically

all of the files in the repo

Click on README.md to edit it

other stuff related to this repo. Notice “Issues”

Add yourself to “People of EEW”

1. Click the pencil to edit the file
2. In the “People of EEW” section, add yourself alphabetized by github handle
1. This uses the Markdown language, search the internet to learn about it!
3. Don’t try to save yet, we’ll talk about that a bit

6

Scroll to the bottom of the file. On saving changes:

• You are going to make a commit (save point), which you label with a commit message describing what you changed
• Choose to make a branch so others can review the changes

7

“commit message”

Extra description (optional)

make a branch

What’s a branch? A pull request? A commit?

8

Start here (main branch of your repo = beginning state of all the files)

Main branch can get commits in the meanwhile

Commits (saves) on your branch

They are merged back together

Ready to make a pull request (suggestion to merge your branch into main)

Save to a branch, and send a PR to suggest merge

​

At the bottom of the file, “Propose file change” to start a pull request suggesting your changes

9

“commit message”

Extra description (optional)

Click when ready

Send a Pull Request

10

Extra description (optional)

Your changes

The version that you are suggesting your changes onto

Brief description of your changes

Click when ready to send pull request

Anatomy of a pull request

• A pull request (PR) on Github is a set of suggested changes, combined with metadata and a place to discuss.

11

Much like an Issue, starts with PR description but can become a discussion

Lists your commits and commit messages

Automatic code quality checks (N/A)

“Files changed”:�Click here to see suggested changes

Viewing changes: “diffs” show what’s different

• On the “Files changed” tab, you can see a “diff” between the suggested version and the one it’s being compared to

12

File name

Toggle between plain text & rendered view

Lines in green have been added

Lines in white are unchanged

Lines in red have been deleted

Line-by-line review

• You can hover over a line and click the blue + that appears to comment on that specific line

13

Overall review

• You can click “Review changes” to leave an overall comment, either approving or suggesting changes

14

Merging changes

• Back in the “Conversation” tab, you can merge or reject the changes:

15

Accept the changes as proposed into your file

Reject the changes (it’s polite to leave a comment explaining why)

What else needs doing? Check out “Issues”

16

join anything, esp with this label

make a new issue

to-dos & conversations

What are we doing this week? “Projects” tab

17

“kanban board” for status of issue

add things to board

“sprint” = tasks we plan to do in that week

Github 101

A 1-Hour Workshop

18

Getting to know you

19

Account & Identity

• Make an account at github.com!
• Your github “handle” = your username (people can @-tag you and you’ll get a notification)
• Your profile is public. See it at github.com/<your username> to find your stuff
• Paste your profile link in the Zoom chat

20

“Repos” (repositories) = folders, kind of

• Make a new repository, just to practice
• Name it “Test repo” or something fun
• Use settings: public, initialize with a README, no .gitignore, GNU 3.0 license

21

“Issues”: Suggested to-dos and conversations

• Go to the “Issues” tab
• Find the “New Issue” button
• Make an issue titled “Needs more descriptive readme”. You can put some description or suggested text in the body of the issue.

22

Tag someone to ask for help

• On your issue, tag one of the other participants in this workshop by writing their @<their username> in the comment and request that they resolve the issue (get their @-handle from the Zoom chat profile links – tag the person who posted their profile just above yours)
• You should now be tagged by someone on an issue – check your notifications!

23

Now you can make a public place online and share it with others!

24

Open Source Culture Note

When you are collaborating with others on Github, in general...

• It’s generally a good idea to tag any people who are relevant to an issue
• This sends them a notification. Otherwise, they are unlikely to see it!
• Notice that you can assign people to issues. In general, assigning yourself is a good way to claim it
• Generally, don’t assign somebody else to an issue unless they ask you to

25

Editing files:�Suggesting changes

26

Make an open source contribution: Communicate!

• On the issue where you’re tagged, comment to say you’re working on it
• Ordinarily, you would chat (on the Issue) to discuss what changes you will be making before you make any edits�(just this one time, you don’t have to do this)

27

Make an open source contribution: Open the file

• Click over to the Code tab (which lists all of the files). Click on README.md to open it.
• Click the Edit pencil, and add a description of why this repo exists. (Bonus: “.md” denotes that this is a Markdown filetype)
• Wait for instructions on how to save the file

28

Wait, what’s a fork? I’m making a fork??

A fork is a version of somebody else’s repo, but that you’re allowed to edit.

​

It’s kind of like a branch…. Read on to learn about branches!

29

What’s a branch? A pull request? A commit?

• Recall that a repo is kind of like a folder
• Git (which Github is based on) lets different people make different “versions” of the set of files contained in a repo— and then merge them back together after review!
• A branch is a specific version of the repo
• A commit is a save, you usually make a “commit message” to identify what was changed since the last one
• A pull request is a suggestion to merge a branch into the main branch (usually the “master” branch)

30

What’s a branch? A pull request? A commit?

31

Start here (main branch of your repo = beginning state of all the files)

Main branch can get commits in the meanwhile

Commits (saves) on your branch

They are merged back together

Ready to make a pull request (suggestion to merge your branch into main)

Scroll to the bottom of the file. On saving changes:

• You are going to make a commit (save point), which you label with a commit message describing what you changed
• Github will automatically make a branch because you don’t own the file you’re proposing to change

32

“commit message”

Extra description (optional)

You save to your branch, and suggest to the owner

• At the bottom of the file, “Propose file change” to start a pull request suggesting your changes to the repo’s owner
• Bonus: write “fixes <link to issue>” in the commit message to automatically resolve the issue

33

“commit message”

Extra description (optional)

Using “fixes” keyword

Click when ready

Send a Pull Request

34

Extra description (optional)

Your changes

The version that you are suggesting your changes onto

Brief description of your changes

Click when ready to send pull request

Now you can suggest changes to files!

35

Open Source Culture Note

When you are collaborating with others on Github, in general...

• Do not push changes directly to the master branch
• Instead, push them to a new branch and send a pull request (PR). This gives all of your collaborators a chance to review your changes (or even just see what they are)
• Make your PR description detailed, maybe even include before & after screen shots, so it’s really clear what’s there
• It’s a good idea to tag people in your pull request to make sure they see it!

36

Editing files:�Reviewing changes

37

Reviewing a pull request

• Check your notifications! Has someone sent a pull request on your repo?
• As a repo owner or maintainer, it’s up to you to review the changes and decide whether to merge them (accept them into your main branch)
• Navigate to Pull Requests on your repo (through notifications or by going to your profile page and clicking into your repo)

38

Anatomy of a pull request

• A pull request (PR) on Github is a set of suggested changes, combined with metadata and a place to discuss.

39

Much like an Issue, starts with PR description but can become a discussion

Lists your commits and commit messages

Automatic code quality checks (N/A)

“Files changed”:�Click here to see suggested changes

Viewing changes: “diffs” show what’s different

• On the “Files changed” tab, you can see a “diff” between the suggested version and the one it’s being compared to

40

File name

Toggle between plain text & rendered view

Lines in green have been added

Lines in white are unchanged

Lines in red have been deleted

Line-by-line review

• You can hover over a line and click the blue + that appears to comment on that specific line

41

Overall review

• You can click “Review changes” to leave an overall comment, either approving or suggesting changes

42

Merging changes

• Back in the “Conversation” tab, you can merge or reject the changes:

43

Accept the changes as proposed into your file

Reject the changes (it’s polite to leave a comment explaining why)

Now you can collaborate on your own & others’ projects!

44

Open Source Culture Note

When you are collaborating with others on Github, in general...

• If you are tagged in a pull request (PR):
• Review it promptly or comment that you don’t have time right now
• Look all the way through “files changed” and make sure everything looks good to you
• If it’s code, try running it
• Put a comment on the “Conversation” tab to say what you reviewed
• In EDGI:
• We usually don’t merge other people’s pull requests, in case they’re still working on something
• It’s usually ok to merge your own PR after ~3 days if nobody comments

45

Project management with Project boards

46

Make a bunch of Issues on your repo

• Issues should be resolvable: a doable (usually small) task or a question that needs an answer (and maybe a conversation)
• Make Issues for EEW events, both long- and short-term
• This is just for practice, so don’t get too detailed

47

Set up a Project (like a Trello board)

• Click Projects tab → Create a project (Automated Kanban w/reviews)

​

• ​
• Click into your new project, then click Add Cards

​

​

• Drag Issues into the To Do column

48

More Project board features

• You can drag project board cards around by hand, or...
• Try resolving one of the issues in your board (on its Issue page “Close issue”) – it will automatically move to Done

You can add notes to the project board, “Convert to issue” if needed

49

Now you can see the status of different tasks all in one place!

50

Project management with Milestones

51

Set up a Milestone

• In your Issues tab, click Milestones

​

​

​

​

• Then make a e.g. “first public EEW event”

52

Assign Issues to the Milestone

• Back in “Issues”, open each issue that needs to be finished in order to reach the milestone�(ctrl+click to open each link in a new tab might be handy)
• On the right side of each issue, set Milestone to associate the issue with the milestone

53

Now you can see progress toward a milestone (on the Milestones page)!

​

54