Whether you’re revisiting a project that you started yesterday, one you worked on last year, or finding a new project that you’ve never worked on, there are quick and easy ways to get oriented with a GitHub project. In this section, you see examples of reorienting with the GitHub Pages website repo that we create in Chapter 3, but the tips apply to any GitHub repo.
To get started, make sure that you’ve opened your browser to GitHub.com and have signed in. If you need to create a GitHub.com account, you can read about how to do so in Chapter 1.
1. Accessing the GitHub.com repo
On the left side of the GitHub.com home page is the list of repositories that you have recently opened, contributed to, or created. Directly above the list is a search bar for searching repositories. This search bar becomes more useful as you interact with more GitHub repositories because the list of repositories can grow large, especially if you belong to a big organization.
At the top of the home page is another search bar that you can use to search for repositories, project boards, and teams (a feature of organizations beyond the scope of this book). By default, this top search bar is scoped to your current context. If you’re on GitHub’s home page, it searches all of GitHub. If you navigate to a repository on GitHub.com, the top search bar searches within that repository.
The search bar always gives you the option to search all of GitHub.com no matter where you are. Figure 5-1 shows the three ways to find a specific repository you may be looking for and two places to find new repositories.
After you find the repository you want to start collaborating with, click it. The repository’s home page appears.
This chapter gives specific examples about contributing to the GitHub Pages website repo that you’re the owner of, so if you want to follow on specifically for that, choose the repo titled your-username.github.io. The repo we use in this example is sarah-wecan.github.io.
2. Verifying your permissions for the repo
If you’re the owner or admin of a repository, you will see a Settings tab at the top of the repository’s home page. You will have complete control over the repository, including the ability to
» Invite collaborators
» Change the visibility of a repository from public to private or from private to public
» Delete the repository
» Archive the repository
If you don’t see the Settings tab, you’re not the owner/admin, but you may have write permissions. To determine whether you do, you can attempt to make a change to a file by navigating to the file and clicking the pencil icon. If you’re able to make a change and are presented with a Commit changes box similar to the one shown in Figure 5-2, you have write permissions and were added as a collaborator for the project.
If you attempt to make a change but see the warning and commit box shown in Figure 5-3, you do not have write permissions and are not a collaborator. You can still create issues and propose file changes to the repo, but you have to get approval from someone with more permissions than you. If you’re interested in how to contribute to projects that you don’t have write access to, see Chapter 6.
3. Orienting yourself with the project
Whether you’re the owner, a contributor, or a new visitor to a repo, you need to orient yourself with the project before you start working in case additional issues, pull requests, or updates have been made since your last visit. Then you’re the only author on a private repo, review what needs to be done before you start so that you can begin something of the appropriate scope given the time you have to work on the project. You don’t want to start building an entire new feature set if you only have a couple of hours; exploring a bug or making some minor updates may be better options.
To get oriented, or re-oriented, with a project, you should review four places on the repo:
» Read the README.md, CONTRIBUTING.md, and CODE_OF_CONDUCT.md files.
Unless you’re working on your own project, you should always read through these three files at least to make sure that you understand how to set up the project on your computer, contribute effectively to the project, and interact with other contributors. Not every project will have all these files, but if they exist, you should read through them to ensure that you’re a positive member of the project’s community. You can find a good example of these documents on the GitHub Desktop open source project at https://github.com/desktop/desktop.
» Survey project boards. If the project uses project boards, look at those boards. Click the Projects tab at the top of the repo and choose a project board. Each project board usually has a column of things in progress or that need to be done. If the project board has automation, then any changes to issues or pull requests (including new ones) will appear on the project board. In the example for this book, the Sarah’s Website project board has four issues listed in the To do column.
» Read through issues. Especially on active projects, folks are likely to have opened new issues. Click the Issues tab at the top of the repo to see the list of open issues. You can sort the issues by most recently updated to see whether folks have commented on existing issues. The default sorting is by newest (meaning the issues that were most recently opened). If you’re the repository owner, triage any new or updated issues. Triaging is when you sort and order items. (See the sidebar called “Triaging issues” for more information about how and why to triage.) The example for this book shows four issues that we opened to help track the progress on our website. No one else has opened up any new issues or commented on them since we last visited the repo.
» Review pull requests. Both passively and actively reviewing pull requests is a good idea before starting to work on a project because they represent the new, removed, or changed code that aren’t yet a part of the master branch. Passively reviewing pull requests means to read through the most recently opened and modified pull requests and see what kinds of contributions to the project are in the pipeline. This review helps to make sure that you don’t start working on something that someone else is either already working on or that may break or contradict something that someone else is already working on.
If you detect a problem, you can add a comment to the discussion on the pull request.
You can also actively review pull requests if have the proper permissions for the project (and, more importantly, if you’re confident that you can evaluate whether the changes should be merged). You can start the review process by opening a pull request, clicking the Files changed tab, and then clicking the Review changes button at the top right of the pull request, shown in Figure 5-4. In the example for this book, no pull requests are open for our website. but we have one that is closed (the initial website template that we added).
Chapter 11 covers the pull request review experience. However if you want to have an interactive experience where you get to review a pull request on your own project before doing it on someone else’s project, you can visit https://lab. github.com/githubtraining/reviewing-pull-requests, authorize, accept Terms and Conditions, install GitHub Learning Labs, and take the automated, self-guided learning lab built by the great folks at GitHub. You can also practice reviewing a pull request on a repo designed specifically for this book, which you can find at https://github.com/thewecanzone/GitHubForDummiesReaders/pull/2.
TRIAGING ISSUES
Just like with an emergency room full of patients, triaging issues is the process of sorting and classifying issues on your repo. Okay, triaging issues may not be just like an emergency room because the issues are hopefully not life-threatening, but they’re often critical for your project. If you’re the owner of a repo on GitHub, we recommend spending the first 30 minutes of your day on a project triaging anything that may have come in since the last time you visited the repo. In the triage process, you should include at least
- Apply labels. Issues and pull requests can have labels associated with them. A few must-have labels are
bug: An issue that reports something that appears to be broken and should be addressed quickly
good first issue: An issue that a new contributor could start with
help wanted: An issue where the code owner is specifically asking for help from the community
needs investigation: An issue with questions that need to be answered before a solution is known
feature/enhancement: An issue that requests a new feature or change to the project
Some labels are added to a repo by default, including: bug, duplicate, enhancement, good first issue, help wanted, invalid, question, and wontfix. You can delete labels you don’t want to use. Other labels can easily be added.
- Respond to comments. Some issues may have new comments since the last time you were on the repo. For example, if someone opened an issue and you applied the label needs investigation and asked for additional information from the person who opened the issue, you may want to check to see whether he or she provided you with any additional information first. Issues should remain active. If they go stale (as in folks stop commenting or making progress on them), they should probably just be closed.
- Close stale issues. Any issues that have gone stale should be closed. One example of when closing an issue is appropriate is when it’s been a few weeks since the person who opened the issue last provided information or you know for a fact that you don’t want to add a requested feature. Always comment on the issue before closing and let folks know why it was closed. These comments are also useful for your future self to remember why you closed an issue.
Source: Guthals Sarah, Haack Phil (2019), GitHub for Dummies, Wiley.