Intro to GitHub:
No Terminal Required

 

Jessica Parsons

Write the Docs SF Bay Area Meetup

 

slides.com/verythorough/github-web

 

 

Adapted from content I originally created for Girl Develop It - Creative Commons BY-NC

Welcome!

What we will cover in this workshop

• Git and GitHub: What's the difference?
• Your GitHub profile and account settings
• Understanding repositories
• Working with files in the GitHub web UI
• Making your first pull request
• Finding and choosing projects and communities

Git and GitHub:
What's the difference?

Git is a Version Control System software that you can
run on your own computer, or on a server

GitHub is a Web-based service for storing, sharing, and collaborating on projects managed with Git

Your GitHub Profile
and Account Settings

Your GitHub Profile

Like a social media profile for open source

You can add information and change settings for:

• your user profile
  • "available for hire" option
• notification preferences
• two-factor authentication
• blocking other users

Your User Account Settings

Understanding
Repositories

What's a Repository?

A repository (or repo, for short) is Git's name for a project, like a folder. It contains all of the project's files and stores each file's revision history.
 

On GitHub, each repository has its own page, and includes several other features for collaboration.

Anatomy of a Repo

The header of a GitHub repository page includes
features that GitHub adds on to Git.

 

Anatomy of a Repo

The file listing displays information common to all Git repositories.

 

 

 

 

 

 

 

        Each row contains:

• a file or folder name
• a description of the last change ( a "commit message")
• when the last change was made

Anatomy of a Repo

GitHub treats some files as special based on their filenames.

 

 

 

 

 

 

These files are designed to help with collaboration.

Working with files
in the GitHub web UI

Creating a repo

Click the ➕ icon in the upper right corner, and select New repository.

Creating a repo

Give the repo a name and a description.

For the purposes of our exercise today, make the repo public.

Creating a repo

GitHub can create some files for you.

• README: an intro page for your project
• .gitignore: useful when using Git on your local machine
• license: terms for other people using with your code

Check the box to add a README.

Adding a file

In the button bar above the list of files,
select Add file > Create new file.

Adding a file

When you're finished, write a commit message
and commit the new file.

We'll talk about committing directly or creating a new branch later.

Uploading a file

You can also upload files that aren't text, like images or videos. (These are called binary files.)

Editing a file

Navigate to a text file you want to change,
and select the pencil icon at the top of the file.

The editor view will open, where you can edit the text and commit your changes.

Writing in Markdown

Markdown is a simple markup language that
many tools use and convert to styled text.

Different symbols translate to different HTML elements.

GitHub's Markdown Guide

Writing in Markdown

GitHub displays all markdown files as styled HTML. Select the Preview changes tab to see how your file will look.

Putting files in new folders

When you create or edit a file, its path
is displayed next to the filename.

Creating "empty" folders

Git tracks files, so an empty folder is a path that leads nowhere. Git won't track empty folders, and you can't create them in GitHub.

 

You can work around this by creating an empty,
throwaway file and giving it a new path.

It's a common convention to call this file .keep.

 

You can delete the file later, after you've
added other files to the folder.

Moving binary files

Binary files like images can't be edited in GitHub,
so you can't change their paths!

Instead, you'll have to:

1. Download the file.
2. Delete it from the repo.
3. Navigate to the new folder.
4. Upload the file again.

Try it!

1. Create a new repo, with a README and a license.
2. Edit the README, and commit your changes.
3. Create a new markdown file with some formatted text.
4. Create an empty folder titled, "images".
5. Navigate to the images folder, and upload an image to it.
6. Add your new image to one of your markdown files. (Hint: use a relative link.)

Forks and
Pull Requests

Forking a repo

When you try to make changes in a repo you don't control,
GitHub will make a fork.

You can also make a fork by selecting the Fork button at the top of the page.

Forking a repo

Forking makes a copy of the repo in your account,
where you can make changes to your copy however you like.
 

A fork remembers where it came from.

However, new changes in the original repo (usually called the "upstream") will not affect your fork, and changes in your fork will not affect the upstream repo.

Proposing changes

You can propose that changes on your fork be applied to the upstream repo by opening a pull request.
 

If you try to edit a file in the upstream repo,
it will give you this option automatically.

Comparing changes

Before you make a pull request, GitHub will compare
the changes you're proposing (on the 'head')
against the repo you want to change (the 'base').

The comparison looks at a specific branch in each repo.
(More on those later.)

Comparing changes

The comparison also includes a detailed
view of all of the changes, called a diff.

Creating the pull request

When you create a pull request (or PR), you add a comment, explaining your change to the maintainers.

Branches

Branches are kind of like forks inside a repo. You can work
in a branch without affecting the rest of the repo.

For example, the "patch-1" branch has changes
that the "main" branch does not.

Creating a branch

To start making a group of changes together, create a new branch.

The new branch will include all of the changes from the branch you were on when you created it.

Usually you will create the branch from the main branch.

Committing to a branch

With your new branch selected, you can make changes as usual. When you commit new changes, you'll have the option
to commit to the new branch.

When you start committing to the new branch, GitHub will show a prompt to start a new pull request. 

You can ignore this until you've made all of your changes.

Your multi-file PR

When you create the pull request from your new branch,
the diff will show all commits, to all files.

Try it!

Make pull requests to someone else's repo.

1. Visit the repo and have a look around.
2. Create a new file, and follow the prompts to fork and propose the change in a PR.
3. Open your fork of the repo, and create a new branch from the main branch.
4. On the new branch, upload an image file.
5. On the same new branch, add a new markdown file with your new image and some text.
6. Open a pull request to merge your new branch into the upstream repo's main branch.

Commenting on PRs

A pull request page opens on the Conversation tab, with the first comment created by the submitter.

Anyone with access to the repo can see and comment on a PR.

Making line comments

The Files changed tab shows the diff. If you hover on a line, a ➕ button will appear. Click it to add a comment attached to that line.

You can add it as a single comment, or start a review.

Creating a review

When you start a review, all of your line comments will be
saved until you're ready to post them together.
Reviews also indicate approval status.

Try it!

1. Open a repo with a PR.
2. Make a line comment in a text file, requesting a change. Make the comment part of a review.
3. Complete your review, adding a summary comment and selecting Request changes.

Accepting feedback

It's totally normal for a pull request to require changes.

Don't be afraid to ask questions for clarification.

Most maintainers are friendly and helpful.
If you encounter one who isn't, consider finding
a different project worthy of your contributions.

Pushing changes to a PR

You can edit files in a PR directly from the View changes tab.

Pushing changes to a PR

To create or upload files for your PR, edit the PR branch in your fork.

All commits to that branch will be included in the PR automatically.

Merging a PR

To merge a pull request, click the Merge pull request button near the bottom of the Conversation tab of the PR.

The changes will be added to the main branch.

Issues

GitHub issues are where collaborators track bugs,
propose features, and discuss changes.
They are for conversation, and do not actually change code.

Anyone with access to the repo can open or comment on an issue.

Filtering issues

Reading a repo's issues is a great way to find out
where you can contribute.

GitHub has several options for searching and filtering issues,
such as finding all issues with a particular label.

Claiming issues

If you find an issue you'd like to work on, avoid duplicating
work by commenting to say you'll volunteer.

Feel free to ask questions if you need clarification before starting!

Closing Thoughts
& Next Steps

Finding more projects

Some friendly repos for making contributions with little or no code:

• "Awesome Lists" are repos with lists of awesome things related to a particular topic. This repo is an awesome list of awesome lists!
• First-Timers' Guide is a repo for first timers to contribute short, single page guides on a variety of tech-related topics.
• San Francisco Write the Docs: Lone Writer's Guide and website
• The Good Docs Project: Find out more in this video of a previous meetup!

Finding more projects

Programs encouraging newcomers and documentarians:

• Digital Ocean's Hacktoberfest: Guides, resources, and events celebrating open source every October.
• Google Season of Docs: 3 month fellowship (with stipend) pairing technical writers with open source projects.

Finding more projects

Some tools for finding newbie-friendly projects and issues:

• Search for issues with common newcomer labels at issuehub.io and up-for-grabs.net.
• Search for PRs with a documentation label. Some might benefit from a writer's review!
• Check out a repo's community profile for indicators of a healthy community.
• Watch the repos of tools you use, or new ones as you're learning them. Read issues and pull requests as they come in to get familiar with the project and see where you can contribute.

Beyond the web UI

The GitHub web UI is a great tool for making quick and easy contributions (even after you've started using more complex tools), but it has some limitations:

• Difficult to sync your fork with the upstream repo
• Can't handle more complex merge conflicts
• Can be difficult to preview changes

As you get more comfortable with open source coding, you may want to learn to use Git from the command line.

Further explorations

Other resources for learning about Git, GitHub, and open source:

• GitHub Guides (by GitHub)
• Kent C. Dodds's GitHub video series
• Shubeksha Jalan's insightful story of her journey into open source
• #open-source channel in Write the Docs Slack

Thanks!

Go forth and contribute!

Questions? Find me in Write the Docs Slack:
username @verythorough