Jessica Parsons
Write the Docs Pittburgh Meetup
verythorough.com/slides/github-web
Adapted from content I originally created for GDISF - Creative Commons BY-NC
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
Like a social media profile for open source
You can add information and change settings for:
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.
The header of a GitHub repository page includes
features that GitHub adds on to Git.
The file listing displays information common to all Git repositories.
Each row contains:
GitHub treats some files as special based on their filenames.
These files are designed to help with collaboration.
Click the ➕ icon in the upper right corner, and select New repository.
Give the repo a name and a description.
For the purposes of our exercise today, make the repo public.
GitHub can create some files for you.
Check the box to add a README.
In the button bar above the list of files,
select ➕(or Add file) > Create new file.
Enter a filename, and your file contents
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.
You can also upload files that aren't text, like images or videos. (These are called binary files.)
Drag or select one or more files, and commit the changes as you would for creating a file.
In the button bar above the list of files,
select Add file (or ➕) > Upload files.
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.
Markdown is a simple markup language that
many tools use and convert to styled text.
Different symbols translate to different HTML elements.
GitHub displays all markdown files as styled HTML. Select the Preview option to see how your file will look.
When you create or edit a file, its path
is displayed next to the filename.
At the beginning of the filename field, type the name of the folder followed by a forward slash.
The folder will be added to the path.
You can do this multiple times, and you can delete folders from the path, too.
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.
Binary files like images can't be edited in GitHub,
so you can't change their paths!
Instead, you'll have to:
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 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.
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.
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.)
The comparison also includes a detailed
view of all of the changes, called a diff.
When you create a pull request (or PR), you add a comment, explaining your change to the maintainers.
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.
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.
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.
When you create the pull request from your new branch,
the diff will show all commits, to all files.
Make pull requests to someone else's repo.
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.
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.
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.
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.
You can edit files in a PR directly from the View changes tab.
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.
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.
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.
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.
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!
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:
For these tasks, you could start working locally with the Git CLI,
or you could try GitHub Codespaces
Codespaces are sandboxed environments in the cloud that work similarly to a local setup using a local code editor (VS Code).
You can create a codespace directly from a repo. It contains all the files and history, and any dependencies you might need to run code.
You can access the file tree and drag files around. Clicking the Source Control sidebar opens a commit interface.
Because the Codespaces environment works like a local one, it can be a good intermediate step to learn more about that way of working, without having to deal with software dependencies and differences between your environment and others.
Some friendly repos for making contributions with little or no code:
Programs encouraging newcomers and documentarians:
Some tools for finding newbie-friendly projects and issues:
Other resources for learning about Git, GitHub, and open source:
Go forth and contribute!
Questions? Find me in Write the Docs Slack:
username @verythorough