GitHub PR Tips
As of May 2024, the TianoCore project transitioned from a mailing list based contribution process to a pull request process. Since many community developers may not be familiar with essential GitHub and pull request features, this guide is meant to show various tips to improve your workflow making it easier to contribute and review changes in edk2.
-
- Forking the edk2 repository
- Setting up notifications for the edk2 repository
- Creating a Pull Request
- Viewing Changes in a Pull Request
- Leaving Feedback in a Pull Request
- Viewing Open & Closed Pull Requests
- Finding a commit
- Finding a Pull Request for a commit
- Contributing entirely in your Web browser
Forking a repository on GitHub creates a copy of the original repository under your GitHub account, allowing you to freely experiment with changes without affecting the original project. You must create a fork of the edk2 repository to create a pull request. To fork the edk2 repository:
- Navigate to the edk2 repository on GitHub.
- Click on the "Fork" button in the upper-right corner of the repository page.
- Select your GitHub username where you want to fork the repository.
- See Fork a Repo for more information.
Once your fork is setup, you can push a branch to the fork with your changes and then create a pull request into the tianocore/edk2 repo from the branch on the fork.
When you fork a repository, you should understand how permissions and settings are transferred to protect your fork.
Notifications help you stay informed about certain activities in the repository. Review the following links to better understand the types of notifications available and how to set them up:
GitHub also provides guidance for filtering emails in your email client. It is recommended to especially review the Filtering email notifications section to learn what options are available.
Creating a pull request is the primary way to contribute changes to a repository on GitHub. There are many ways to create a pull request depending on whether you are using the GitHub Web UI or a tool like GitHub Desktop, VS Code, the GitHub CLI, or another tool.
The quickest approach when using the GitHub Web UI is to push the branch to your forked repository and then visit the tianocore/edk2 repo. The UI will conveniently display an option to create a pull request from the branch you just pushed to your fork.
- See Creating a Pull Request for more information.
Prior to the current pull request process, pull requests were created to test changes against CI and then closed. Now,
any pull requests that are not targeting completion to the master branch must be marked as a draft pull request.
This still allows PR status checks to run but it indicates that maintainers should not review the pull request.
To create a draft pull request in the GitHub Web UI, click the down arrow next to "Create Pull Request" and select "Create Draft Pull Request". An example of how to do this is shown in the link below.
Pull request reviews can also happen in a number of different tools. When first getting started, try out a few options and see what works best for you. Many users start with the GitHub Web UI but find that it is not as feature-rich as other options.
For example, I prefer to review code within the context of the full codebase so surrounding code is readily displayed and I can easily search across the codebase while reviewing. This is why I tend to use VS Code with the GitHub PR extension when reviewing a non-trivial change. I can review code with the same level of IDE support used when writing code and it is easy to leave comments, code suggestions, and respond to conversations. It also allows code to easily be checked out locally to test the changes and make any modifications on top.
Suggested reading:
The edk2 project requires that conversations be resolved before a pull request can be merged. Conversations are typically resolved by clicking a "Resolve conversation" button. Comments left in a code file whether on a specific line of code or as a general file comment must be resolved.
If you would like to simply leave a comment without requiring a resolution, you can leave a comment outside of a file such as in the comment box at the bottom of the pull request.
The above link also shows how you can leave a code suggestion for a section of code in a pull request. The following link shows how the author of a pull request can apply a code suggestion.
There are many ways to view pull requests. The most common view is to navigate to the "Pull requests" tab of the repository. There you can quickly filter by open/closed status, author, labels, review status, and more. In addition, the PR status check status is displayed next to each PR.
You can find all of the pull requests and issues you've created and been asked to review across repos specific to your account by going to the dashboard by clicking the buttons described in Viewing all of your issues and pull requests.
To locate a specific commit within the repository's history.
- Go to the repository on GitHub (e.g., edk2).
- Click on the "
<X> Commits" button where<X>is the number of commits currently in the selected branch. - Click the commit.
Note: If you have a commit hash, for example
4b6ee06a090d956f80b4a92fb9bf03098a372f39, you can append it to the repository URL to view the commit directly. For example, https://github.com/tianocore/edk2/commit/4b6ee06a090d956f80b4a92fb9bf03098a372f39.
Once you have a commit hash/URL such as https://github.com/tianocore/edk2/commit/4b6ee06a090d956f80b4a92fb9bf03098a372f39,
you can quickly find the associated pull request by looking for the pull request link next to the branch name. In the
example below, clicking #5639 will take you to the pull request.
Other tools also provide ways to find the pull request for a commit. For example, it is possible in the GitHub CLI to use:
>$ gh pr list --search "4b6ee06" --state mergedIn an IDE like VS Code with the recommended extensions installed, you can simply hover over a line of modified code to see the commit and pull request information for the change:
If you contribute infrequently or want to make a quick change on a system without setting it up for development, you might be interested in GitHub Codespaces. Using Codespaces, you can work entirely in your Web browser in a feature rich environment that includes a terminal, code editor, and more to submit your change. GitHub provides a number of free hours per month for Codespaces usage.
The edk2 project provides a Fedora and Ubuntu dev container you can use for your Codespaces environment.
A lighter weight and completely free alternative to simply edit files your Web browser is to use the built-in editor in the GitHub Web UI called the github.dev web-based editor. This allows you to edit files in your browser, create branches, and PRs without having to clone anything locally. This might be useful if you are making very light changes such as editing text files or updating Python dependencies and your changes can entirely be tested in the PR status checks.
The VS Code GitHub Pull Requests and Issues extension allows seamless integration of GitHub pull requests and issues directly within the VS Code editor. This provides a powerful interface for reviewing and managing pull requests without leaving your development environment.
Review's the extension's documentation to learn how to use it effectively.
It is recommended to install these extensions as well to make the most of git and GitHub integration in VS Code:
GitHub CLI (gh) is the official command-line tool for interacting with GitHub repositories and pull requests. With GitHub CLI, you can interact with GitHub directly from the terminal. It is open-source and available for Linux, macOS, and Windows.
GitHub Desktop is a user-friendly application for managing GitHub repositories on your desktop. If you find the command-line interface intimidating and would prefer not to use VS Code with extensions, the GitHub Desktop application is a great alternative.
It provides an intuitive interface for performing common Git operations, including creating branches, committing changes, and managing pull requests. If you are new to git, you might also find the GitHub desktop documentation helpful for getting started.