Pull Request Guide

Fedora dist-git repositories allow pull requests, which makes it possible for anybody to contribute to any package without having maintainer status. Package maintainers may also choose to use pull requests to allow co-maintainers to review the proposed changes, and hook into dist-git Continuous integration.

The same packaging tools and workflows that maintainers use can be used for pull request contributions, with the exception of certain privileged operations that can only be performed package maintainers, such as submitting a Bodhi update.

This guide describes one possible workflow for submitting a pull request. See Package Maintenance Guide for more comprehensive tooling guide. It contains many options that can be used to create other workflows.

This guide assumes that you are creating a pull request to a package named some-package. The target branch for the pull request is assumed to be rawhide, as Rawhide is much more common change target than release branches. Any other release, such as f40, would mostly differ in branch name.

This guide also assumes you are not a member of the packager group, with separate notes in places where packagers should do something differently.

When to make a pull request?

In general, the reasons for making pull requests to Fedora packages are similar to reasons for making pull requests to any open source repository. Either you are a user of the package and want to improve it for you own use, or you are contributing to another project or package and need to change something to unblock your own work. Or you find something that can be improved while inspecting the package repo, and submit a pull request just to help the maintainers.

A Fedora-specific reason is the packager sponsoring process, which requires a packager candidate to demonstrate their packaging skills, which can very conveniently be done via submitting pull requests.

A very common, and often simple, case is that Fedora’s version of a package is not the latest upstream release. Package may also miss optional dependencies or use sub-optimal build options, so that all features offered by upstream do not work on Fedora.

Prerequisites

You need a Fedora account. In Installing Packager Tools, you also need to follow sections Installing and Configuration / Mock.

Cloning the repository

Usually, package maintainers work directly in package’s dist-git repository, to which only they have access to. For pull requests, using a fork is necessary. While it is possible to create a fork using src.fedoraproject.org web interface and close it using plain Git commands, fepdkg fork provides a convenient and simple CLI-based method.

fedpkg clone --anonymous some-package
cd some-package
fedpkg fork

In case fedpkg fork complains about missing Pagure token, follow the instructions given in the error message.

These commands result in a local Git repository with remotes: origin for package’s official dist-git repository in fetch-only mode, and another one with you Fedora username pointing your fork that can also be pushed to:

$ git remote --verbose
origin    https://src.fedoraproject.org/rpms/some-package.git (push)
username  ssh://username@pkgs.fedoraproject.org/forks/username/rpms/some-package.git (fetch)
username  ssh://username@pkgs.fedoraproject.org/forks/username/rpms/some-package.git (push)

Branching

Just as you would for any other pull request for any other project, create a Git branch for your changes:

git switch -c my-changes

Make changes

For pull requests, making local changes and testing the changes locally is just the same for maintainers. For example:

# change the required things in the specfile.
gedit some-package.spec
# download the referenced sources to local machine
spectool -g some-package.spec
# check that the changes you made still build
fedpkg mockbuild
# Install and test the package

Updating sources

Only members of the packager group can update sources to lookaside cache. If downloaded source needs to be changed, the best a non-packager can do is to update the sources file with the correct checksum:

fedpkg new-sources --offline some-package-1.2.3.tar.gz

If you are in the packager group, you can remove --offline from the command, so that the source archive is uploaded. Otherwise, the maintainer who eventually merges the pull request has to do that. In that case, make sure that the merge request uniquely points to the source archive. Usually, that is done by using a URL in specfile’s Source tag, but if not, a specfile comment can be used.

Committing and pushing

Create a commit from your changes, write a sensible commit message, and push your branch to your fork:

git add <changed files>
git commit
git push username HEAD

Note that if the package uses rpmautospec, the commit message will be parsed to create the package changelog entry.

Creating pull request

When you push your changes to your fork, you get a link for creating a pull request as output:

remote: Create a pull-request for my-changes
remote:    https://src.fedoraproject.org/fork/username/rpms/some-package/diff/rawhide..my-changes

You can also create pull request for any branch in the Pagure web UI for your fork.

The pull request form asks you to fill description, which is auto-filled with commit changelog. Write any pertinent information there and submit.

If you could not populate the lookaside cache in Updating sources step, include that info and ask for a maintainer to do that.

Continuous integration

Dist-git repositories are connected to CI by default. For all pull requests, a Koji scratch build and installability test is done. Results for these appear in the pull request’s web page when they are available. Even though failing CI does not block merging, the CI results should be green. If CI fails, it is a good idea to fix that.

If you need to re-run the test build in pull requests, a comment with [citest] will do so.

Package maintainers may also enable more advanced Zuul CI.

Review

Pull request review is just like for any other open source project. Hopefully, a maintainer quickly responds to your pull request and either simply merges it, asks questions or requests changes. Answer questions, do the requested changes and push them to the same branch.

Note that many Fedora packages are maintainer by volunteers, and there are not hard limits for the expected response time for pull requests. Because of this, the review may only come after days or weeks. In case you feel that response takes too long, you can (and should) follow the steps in Non-responsive maintainer policy.

After the merge

The pull request is complete when a maintainer has merged it. Afterwards, the maintainer still needs to:

  • Update the lookaside cache, if you could not do it.

  • Submit a build with fedpkg build (since any packager can do this for any commit in a release branch for any package, if you are a packager, you can theoretically also do this. But in practice it will be the maintainer who merges your pull request, because they can start the build immediately after they merge.)

  • In case changes were done to branch other than rawhide, submit a Bodhi update.

Want to help? Learn how to contribute to Fedora Docs ›