Package Maintenance Guide

This retrieves a copy of the package sources from the server. It’s known as your 'working copy'.

This pulls any sources stored in the "lookaside cache" (see below for more). Steps like fedpkg prep and fedpkg srpm will do this if necessary, but you may want a copy right away.

This is not an RPM packaging guide, so we’ll assume you know what you’re doing here. New sources and patches go in the working copy directory for now.

Extract source, apply patches etc. within the checkout directory:

This is useful for making sure your patches apply cleanly, and inspecting the source tree if you need to do so.

This is the simplest kind of test build, but it’s usually cleaner and a better test to do a Mock or Koji scratch build (see below).

This fires off a Mock build, if you have Mock configured correctly. Using Mock to Test Package Builds can help there.

You can request a Koji scratch build (a test build, which will not go to any repository) of the generated .src.rpm with the koji build --scratch command (see man koji).

See Koji scratch builds.

This is handy for making sure you did not touch something by mistake, or forget to bump the release, or forget to include a changelog.

If you want to whitelist some rpmlint errors and prevent them from appearing, you can create an rpmlint config file named <source_package_name>.rpmlintrc and it will get applied.

Git does not consider all files in the working directory to be a part of the git repository by default (handy for keeping other files around that are relevant, like the source tree). This tells git to start considering these files as part of the repository locally. When you commit and push later, this change is communicated to the server.

'Pristine' upstream sources (like release tarballs) and other larger source files are stored in the lookaside cache system, not committed directly to git. This provides more efficient storage and transfer of the files. The sources and .gitignore files in the repository keep it in sync with the lookaside cache. Any time you use fedpkg new-sources or fedpkg upload, you must remember to commit changes to those files.

new-sources 'starts from scratch', replacing all files currently in the lookaside cache. You will typically use this command for many packages with just a single source tarball, each time you update to a new upstream version. upload just adds the given file to those already in the cache. Do remember not to leave stale sources lying around.

Each Fedora release has its own branch in each package repository so different builds can be sent to each release. See below for more details on working with branches.

This command extracts your package changelog entry to the file clog, so you can use it as the git changelog if you like. Some maintainers draw a distinction between the two, some do not.

This behaves by default like git commit -a: It stages modified files and commits all at once, though it does not add files which git is not yet tracking.

This creates a sort of bundle, a 'commit', of your changes to the repository, with a unique identity and a changelog. Other maintainers — and you yourself, later — can view the history of changes to the repository with the commit as the finest level of detail. It is good practice to use many relatively small commits, each for a single purpose. Do not combine a version bump with a bunch of whitespace fixes and some scriptlet changes all in one commit, create separate commits for each.

The -F clog parameter will use the clog file from the previous step as the changelog. -p will push (see below) at the same time as committing. -c combines the clog and commit -F clog steps into one, if you like that.

This sends all the new commits in your local working copy to the upstream server. If you are still learning the system, now is a good time to fedpkg co another copy of the repository somewhere else, compare what you get to your working copy, and run a test build on it.

See Container Layered Image Build for details.

Unlike most of the above commands, this operates on the state you have pushed to git, not the local state. If you have issues make sure you have pushed and committed all patches and handled the sources correctly.

See Updating inter-dependent packages if you are making inter-dependent changes to more than one package.

This command will request a git branch for Fedora 40.

This command will request git branches for every currently active Fedora release.

This form can be used to request branches when not inside package’s Git repository. You do not need to wait for your repository to be created before filing such branch request, but you should request the repository before requesting branches.

This command will request a git branch for EPEL 9.

You can maintain each branch entirely separately, if you like, laboriously copying changes between them (so long as you always stay within the Updates Policy requirements). However, git provides us with several handy tools for working with branches. Here’s an example:

This will merge the changes from the rawhide branch to the f40 branch. Git aficionados may note this is a somewhat unusual workflow, but it is appropriate to the context of package management. Remember, after pushing to and building for a stable release or a Branched release after updates-testing activation, you will have to submit an update before any other Fedora users will see your build.

Note that merges will only be sure to work cleanly so long as the branches have not previously diverged. That is, if you do this:

you may encounter a merge conflict.

Remember that git is a collaborative system, and used as such in Fedora package management. It is often the case that you must consider changes made by others in working on a package, and consider how your changes will affect others.

This is a large topic and somewhat beyond the scope of this guide, but we can give basic pointers. There are other good references in the Git book and at GitHub Docs.

When you merge and a conflict occurs, you can edit the files that have conflicts. Remove the conflict markers in the files and merge the changes manually. Use git diff or fedpkg diff to inspect the changes against the pre-conflict state and verify you are happy with the resolution. Then you can commit the files with fedpkg commit or git commit -a. Git will know if you have resolved the conflict by checking that all the conflict markers have been removed.

Git provides a graphical diff program to help resolve conflicts. This can be handy for visualizing what changes have occurred and dealing with them as a set.

If you use git commands to branch and checkout directly, you can define whatever local branch names you want. If you use fedpkg switch-branch, it will default to creating the names used in the examples above.

It is often helpful to know what branch you are working on at a glance. You can add this information to your bash prompt with the information here.

Here is the scenario: You have built your package successfully on the f40 branch, but there is a problem keeping your package from building on last.

Solution: Make your changes in the branch and then add a digit to the very right of the release tag. There is no need to change the release in the other branches. This allows upgrades to work smoothly if the user upgrades to a newer release of Fedora.

Then tag and build as usual. This approach was initially discussed in this mailing list thread.

From time to time you may want to remove a package build you submitted to Rawhide or to Branched prior to the Alpha freeze (both cases where the build would usually go out to the main repository without further gating). This could happen in a situation where a bug or issue is found in your package that will be resolved upstream in the next release, or you realize you made a significant mistake in the build that cannot easily be corrected.

You can remove the package by using Koji:

where foo-1.1.3-1.fc41 is replaced with the name of your package build. See koji help or Using the Koji Build System for more information.

The recommended option is to include VerifyHostKeyDNS yes in your ~/.ssh/config file. This will result in using DNS to check that the key is correct.

But you can also manually check against the list of keys at Fedora Apps. The strings there are what ends up in your ~/.ssh/known_hosts file. So you can accept the fingerprint when prompted and then check that the correct string for src.fedoraproject.org ended up in your ~/.ssh/known_hosts file.

The fedpkg tool clones repositories using the ssh:// protocol, so this should not be a problem normally (as long as you have your ssh key). If you cloned using the git utility itself, check the .git/config file to ensure the remote repository is being accessed via an ssh:// protocol, and not git://.

Pushing to your forked repository using http might fail with an error like this: