Package Maintenance Guide
This page provides some basic instructions for day-to-day usage of the git-based package maintenance system for Fedora. It is intended primarily for new and current Fedora package maintainers, but does briefly cover anonymous read-only use of the system. It is not a guide to RPM packaging per se.
Some pre-existing knowledge of git may be useful, but is not a pre-requisite. In fact, Fedora packaging can be a relatively painless introduction to it.
You may have been looking for, or also be interested in:
Installing Packager Tools
Follow Installing Packager Tools.
Common fedpkg commands
This section lists typical fedpkg commands in a normal workflow, with short descriptions. In this workflow, we will be operating on the Rawhide branch of the package.
Check out a package
fedpkg co <source_package_name> cd <source_package_name>
This retrieves a copy of the package sources from the server. It’s known as your 'working copy'.
Retrieve package sources
fedpkg sources
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.
Make your changes to the package
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.
Run the prep stage
Extract source, apply patches etc. within the checkout directory:
fedpkg prep
This is useful for making sure your patches apply cleanly, and inspecting the source tree if you need to do so.
Do a local build of the current state
fedpkg local
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).
Do a mock build of the current state
fedpkg mockbuild
This fires off a Mock build, if you have Mock configured correctly. Using Mock to Test Package Builds can help there.
Generate a .src.rpm from the current state
fedpkg srpm
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
).
Do a scratch build using Koji
See Koji scratch builds.
Check changes you have made
fedpkg diff
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.
Run some checks (rpmlint) on your package
fedpkg lint
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.
Stage any small patches or new source files for commit
git add SOMEFILE
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.
Upload new source files to the lookaside cache
fedpkg new-sources
WARNING: This will replace the current list of source files, not add to it.
fedpkg upload
'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.
Switch to a different release branch
fedpkg switch-branch <f40,el9,rawhide>
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.
Generate git changelog from package changelog
fedpkg clog
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.
Commit changes
fedpkg commit (-F clog) (-p) (-c)
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.
Push changes
fedpkg push
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.
Submit 'official' builds from a stream branch
fedpkg build
There is no difference in the command line
to submit multiple builds from a stream branch.
But you need to create a config file package.cfg
in the repository
and set option for the builds.
For example config file is created in a stream branch 8
of package foo
, which has content:
[koji] targets = f40 epel9
This example shows when you execute the build
command,
fedpkg
is able to submit builds for releases, f40
and
epel9
.
In practice, you are able to specify two shortcut names fedora
and epel
for convenience.
fedpkg
retrieves current active Fedora and EPEL releases automatically.
Hence, if you do not want to select a subset of releases,
or just simply going to build packages for active releases
without knowing the concrete release name,
shortcut names would be helpful.
You can specify to build for rawhide
, use name master
.
Do a Container Layered Image Build
fedpkg container-build
See Container Layered Image Build for details.
Submit a package update for the latest build
fedpkg update
This is the first point at which you might possibly cause real mess for a real user, so use it with caution. If you are following the example and operating on Rawhide, your build would go live for Rawhide users some few hours after you ran this command. |
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.
Typical fedpkg session
A typical session may look like this:
fedpkg clone foo cd foo fedpkg sources fedpkg new-sources foo-0.0.2.tar.bz2 # Change the required things in the specfile. # 'rpmdev-bumpspec' is useful for simple version updates. gedit foo.spec # Check that the changes you made are correct. fedpkg mockbuild fedpkg diff fedpkg lint fedpkg commit -p -c # commit and push in one go
Working with branches
Each Fedora and EPEL release has a corresponding branch in the git repository. You can switch between them like this:
fedpkg switch-branch rawhide fedpkg switch-branch f40 fedpkg switch-branch f39 fedpkg switch-branch epel9
When the git repository is created,
it will only have a rawhide
branch and a main
branch,
the latter being an alias to the former.
Branches for new Fedora releases going forward are created automatically during
mass branching.
If you would like to build your package for existing releases of Fedora or EPEL,
you will need to explictly request those branches.
Requesting branches
fedpkg request-branch f40
This command will request a git branch for Fedora 40.
fedpkg request-branch --all-releases
This command will request git branches for every currently active Fedora release.
fedpkg request-branch --repo <source_package_name> f40
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.
fedpkg request-branch epel9
This command will request a git branch for EPEL 9.
Merging between branches
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:
fedpkg clone bzrtools # Make some changes in the rawhide branch fedpkg new-sources bzrtools-2.2.tar.gz gedit bzrtools.spec fedpkg commit fedpkg switch-branch f40 git merge rawhide # for push into repo fedpkg push
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:
fedpkg clone bzrtools # Make some changes in the rawhide branch fedpkg commit fedpkg switch-branch f40 # Make some changes in the f40 branch fedpkg commit fedpkg switch-branch rawhide # Make some more changes in the rawhide branch fedpkg commit fedpkg switch-branch f40 git merge rawhide
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.
Resolving merge conflicts
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.
Using git mergetool to resolve conflicts
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.
git config --global merge.tool meld fedpkg switch-branch f{{FedoraVersionNumber}} git merge rawhide # Conflicts occurred. # Open a meld showing a three way diff of the merge, working tree, and the last commit. git mergetool # Resolved all the conflicts in the GUI git add CONFLICTEDFILES git commit
Multi-package updates
When a change to a package affects a large number of dependencies (e.g. all perl, python, ruby or ghc packages), requiring them to be rebuilt, it may be better to initially do the builds in a side tag, so that there is less disruption in Rawhide. See Package Update Guide, section Multi-package updates for details.
Using fedpkg anonymously
You can use fedpkg like this:
fedpkg clone --anonymous
to check out a package without requiring identification. Obviously, you will not be able to push any changes to this repository, but it is useful for non-packagers who simply want to examine a package and make changes for their own use.
If the intention is to submit changes to a Fedora developer, see Pull Request Guide.
Tips and tricks
Local branch names
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.
Current branch and state in shell prompt
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.
Importing a .src.rpm to update
The command usually used to initially populate a git package repository
from a .src.rpm that has been through the Package Review Process
can also be used to update a normal working copy,
if you have an old-school packaging process
to which you are particularly attached.
Just run fedpkg import file.src.rpm
and it will upload new tarballs into lookaside cache,
update a working copy of the last version found in git,
and commit all changes.
fedpkg import --help
documents some other parameters it can accept.
This approach makes it harder to verify that your changes are safe and do not overwrite changes made to the package by others. For this reason, its use is not recommended. |
Making changes on an older branch without breaking the upgrade path
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.
Name: foo Version: 1.0 Release: 1%{?dist} Name: foo Version: 1.0 Release: 1%{?dist}.1
Then tag and build as usual. This approach was initially discussed in this mailing list thread.
Removing a package build pending for Rawhide or Branched
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.
This should only be done on the same day of the build, before it is included in a compose. If your build was already included in a compose you must not untag it! Check the Product Definition Center to get the starting time of the last compose. |
You can remove the package by using Koji:
koji untag-pkg f41 foo-1.1.3-1.fc41
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.
ssh fingerprint
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.
Problems connecting to the repository
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://.
Problems pushing to forked repository using http
Pushing to your forked repository using http might fail with an error like this:
Please visit https://id.fedoraproject.org/openidc/Authorization?scope=openid+https%3A%2F%2Fid.fedoraproject.org%2Fscope%2Fgroups+https%3A%2F%2Fmbs.fedoraproject.org%2Foidc%2Fsubmit-build+https%3A%2F%2Fsrc.fedoraproject.org%2Fpush&response_type=code&client_id=fedpkg&redirect_uri=http%3A%2F%2Flocalhost%3A12345%2F&response_mode=query to grant authorization
127.0.0.1 - - [14/Jun/2024 21:23:41] "GET /?error=invalid_scope&error_description=unknown+scope+https%3A%2F%2Fmbs.fedoraproject.org%2Foidc%2Fsubmit-build+requested HTTP/1.1" 200 47
No token received.
fatal: credential helper '/usr/bin/fedpkg gitcred' told us to quit
Could not execute push: Failed to execute command.
This is caused by fedpkg
failing to connect to MBS which has now been decomissioned. Removing the reference to MBS in /etc/rpkg/fedpkg.conf
should fix this.
Change this line in fedpkg.conf
:
oidc_scopes = openid,https://id.fedoraproject.org/scope/groups,https://mbs.fedoraproject.org/oidc/submit-build,https://src.fedoraproject.org/push
to:
oidc_scopes = openid,https://id.fedoraproject.org/scope/groups,https://src.fedoraproject.org/push
It builds here, why doesn’t it build there?
Is your package building locally
— even with Mock, even as a scratch build!
— but not when you run fedpkg build
?
Before you get too frustrated,
remember fedpkg build
runs on the package as it exists in the upstream repository,
not your local working copy.
Make sure you have committed and pushed all changes and source files,
and handled the lookaside cache correctly.
Other issues that have been reported,
are issues because of build/make check parallelization
and failures because of test suites that depend on operations finish on precise timing
(and a busy build system may not be able to perform operations on time).
Want to help? Learn how to contribute to Fedora Docs ›