As of May 2024, the TianoCore project transitioned from a mailing list based contribution process to a pull requestprocess. Since many community developers may not be familiar with essential GitHub and pull request features, this guideis meant to show various tips to improve your workflow making it easier to contribute and review changes in edk2.

1. GitHub UI key features

   • 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

2. VS Code GitHub PR plugin

3. Official GitHub CLI tool

4. Official GitHub Desktop application

Forking a repository on GitHub creates a copy of the original repository under your GitHub account, allowing you tofreely experiment with changes without affecting the original project.You must create a fork of the edk2repository to create a pull request. To fork the edk2 repository:

1. Navigate to the edk2 repository on GitHub.
2. Click on the "Fork" button in the upper-right corner of the repository page.
3. Select your GitHub username where you want to fork the repository.

• SeeFork 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 thetianocore/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.

• SeeAbout permissions and visibility of forks

Notifications help you stay informed about certain activities in the repository. Review the following links to betterunderstand the types of notifications available and how to set them up:

• About Notifications
• Configuring Notifications

GitHub also provides guidance for filtering emails in your email client. It is recommended to especially review theFiltering email notificationssection 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 tocreate 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 thetianocore/edk2 repo. The UI will conveniently display an option to create a pullrequest from the branch you just pushed to your fork.

• SeeCreating 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 themaster 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.

• SeeIntroducing draft pull requests

Pull request reviews can also happen in a number of different tools. When first getting started, try out a few optionsand see what works best for you. Many users start with the GitHub Web UI but find that it is not as feature-rich asother options.

For example, I prefer to review code within the context of the full codebase so surrounding code is readily displayedand I can easily search across the codebase while reviewing. This is why I tend to use VS Code with the GitHub PRextension when reviewing a non-trivial change. I can review code with the same level of IDE support used when writingcode and it is easy to leave comments, code suggestions, and respond to conversations. It also allows code to easilybe checked out locally to test the changes and make any modifications on top.

Suggested reading:

• About PR reviews
• Reivew proposed changes

The edk2 project requires that conversations be resolved before a pull request can be merged. Conversations aretypically resolved by clicking a "Resolve conversation" button. Comments left in a code file whether on a specificline 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 filesuch as in the comment box at the bottom of the pull request.

• Comment on a PR

The above link also shows how you can leave a code suggestion for a section of code in a pull request. The followinglink shows how the author of a pull request can apply a code suggestion.

• Incorporate feedback

There are many ways to view pull requests. The most common view is to navigate to the"Pull requests" tabof the repository. There you can quickly filter by open/closed status, author, labels, review status, and more. Inaddition, 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 youraccount by going to the dashboard by clicking the buttons described inViewing all of your issues and pull requests.

To locate a specific commit within the repository's history.

1. Go to the repository on GitHub (e.g.,edk2).
2. Click on the "<X> Commits" button where<X> is the number of commits currently in the selected branch.
3. Click the commit.

Note: If you have a commit hash, for example4b6ee06a090d956f80b4a92fb9bf03098a372f39, you can append it to therepository URL to view the commit directly. For example,https://github.com/tianocore/edk2/commit/4b6ee06a090d956f80b4a92fb9bf03098a372f39.

• About commits
• Searching commits

Once you have a commit hash/URL such ashttps://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 theexample 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 CLIto use:

>$ gh pr list --search"4b6ee06" --state merged

In an IDE like VS Code with the recommended extensions installed, you can simply hover over a line of modified code tosee 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, youmight be interested inGitHub Codespaces. Using Codespaces, you can workentirely in your Web browser in a feature rich environment that includes a terminal, code editor, and more to submityour change. GitHub provides a number of free hours per month for Codespaces usage.

The edk2 project provides aFedoraandUbuntudev container you can use for yourCodespaces environment.

• GitHub Codespaces overview
• TianoCore containers

A lighter weight and completely free alternative to simply edit files your Web browser is to use the built-in editorin the GitHub Web UI called the github.dev web-based editor. This allows you to edit files in your browser, createbranches, and PRs without having to clone anything locally. This might be useful if you are making very light changessuch as editing text files or updating Python dependencies and your changes can entirely be tested in the PR statuschecks.

• The github.dev web-based editor

The VS Code GitHub Pull Requests and Issues extension allows seamless integration of GitHub pull requests and issuesdirectly within the VS Code editor. This provides a powerful interface for reviewing and managing pull requests withoutleaving your development environment.

• GitHub Pull Requests and Issues

Review's theextension's documentation to learn howto use it effectively.

It is recommended to install these extensions as well to make the most of git and GitHub integration in VS Code:

• Dev Containers
• GitLens
• Git History

GitHub CLI (gh) is the official command-line tool for interacting with GitHub repositoriesand pull requests. With GitHub CLI, you can interact with GitHub directly from the terminal. It is open-source andavailable for Linux, macOS, and Windows.

• Installation Instructions
• GitHub CLI Manual

GitHub Desktop is a user-friendly application for managing GitHub repositories on yourdesktop. If you find the command-line interface intimidating and would prefer not to use VS Code with extensions, theGitHub Desktop application is a great alternative.

It provides an intuitive interface for performing common Git operations, including creating branches, committingchanges, and managing pull requests. If you are new to git, you might also find the GitHub desktop documentationhelpful for getting started.

• GitHub Desktop documentation