Package update HOWTO
This document shows how to update a package you maintain in Fedora. It assumes you already have a package in the Fedora repositories.
This document is divided in three sections to give Developers, Testers, and Mirror Admins some guidelines on how to submit packages for
rawhide, development and
- For more guidance on package updates, refer to Updates_Policy.
Here you can find detailed information on process of Package Management in Fedora. If you want to know the difference between
rawhide, development and
pending , and which one is suitable for you, along with an overall understanding of the release naming and repos, visit our new and improved Fedora Development Process Overview page.
New contributors (mandatory reading), new Testers (highly suggested reading), new Consumers (useful reading), or anybody interested in how Fedora is developed would find this page useful.
In particular, these are the new paths on mirrors:
/pub/fedora/linux/development/rawhide/will become the new path of Rawhide. It will continue to not have install images, and will be the place where builds from the
"devel"branch in git go to. It'll be Fedora 21 intended content.
/pub/fedora/linux/development/20will become the new path of the branched Fedora 20 content. This is where builds from the F-20/ branch in git will go after they pass through Bodhi as "stable".
/pub/fedora/linux/updates/testing/20/will be where potential Fedora 20 builds go after passing through bodhi as "testing". This is where you'll find the latest stuff proposed for freeze break and where testing and peer review of these freeze breaks will happen. When a maintainer feels enough testing has happened, or enough karma triggers the Bodhi auto request, the build will be marked "stable" and show up in the development/20 tree at the next nightly compose.
|Check out and build from the devel/branch||No action required. Happens nightly automatically||Check out and build from the F21/branch||Request a testing update in Bodhi for F21. Bodhi admins push it.||Peers test the update and provide karma feedback via Bodhi||Request a push to stable within Bodhi. Bodhi admins push it.|
|Build for Rawhide||X|
|Build for Rawhide + testing in other branches||X|
|Build non-critical path package for F21 (branched)||X|
|Build critical-path for F21 (branched)||X|
|Push critical-path package waiting in "pending" updates-testing repo for a week without karma feedback||X||X|
|For a package, in critical path, in the "pending" updates-testing repo for a week that hasn't received karma feedback||X|
|To mark, built package for F21, available for testing||X||X|
|To mark stable and tagged for F21 tested update||X|
|To push a package built to handle an urgent issue (e.g. security problem, non-functioning system, etc.) to the F21 branch ||X|
- Mutually exclusive.
- Query QA/Release Engineering, too
- Provided the package has net positive Karma from QA or releng and at least one more net positive karma point. If karma autopush is checked submit to stable is done automatically
- In all cases, it's necessary to be very very very sure the update will not cause additional problems
- If the package is not in the critical path, nor addressing a security problem, then it can be requested a push to stable
If the package addresses a security issue then it should be marked as security. Wait for the Security team to sign off on the update (not sure how this happens right now) before requesting the package be pushed to stable
If the package is in the critical path, then wait for a QA/Release Engineering/Peer net positive karma vote in Bodhi before requesting the package be pushed to stable
|File a buildroot override tag request as outlined in the Policy page, and proceed to build the package||Issue the Bodhi request|
|To build a package for the Pending F21 which requires a package not yet pushed stable for F21||X||X|
|Read the Rawhide page and follow instructions||Keep the rawhide repo enabled and fedora, updates, & updates-testing repos disabled.||Consume the rawhide firehose and report issues as you find them.||Install from Alpha, Beta, the Last Known Good Pending snapshot or a Pending nightly live image||
||Update your Fedora 12 system by reading instructions at FIXME||Check the QA/Join page that describes the different testable repos, skill level and investment involved.||Read the Package Acceptance Test Plan and use it as a guideline|
|To install Rawhide on your system to test the latest packages||X||X||X|
|To install and run Fedora 21 as your desktop and participate in test days||X||X|
|To update a Fedora 12 system to the Pending Fedora 13 for testing||X|
|To provide test feedback for new packages||X|
|To represent the QA team in providing feedback on critical path package updates||X||X|
For Mirror Admins
- If you are a mirror admin and want to prepare for additional repos coming to your mirror :
mirror-list(-d)and watch for announcements regarding new paths being added to the Master Mirror.
- Check your sync exclusion settings to ensure you either get, or don't get the new path (depending on your needs).
Build a package for Rawhide
To build a package for Rawhide, check it out from the git devel/branch.
Install fedora-packager if not already installed.
Check out a local working copy of the git module you plan to edit, e.g. (for a description of the directory layout, see the Anatomy page:
fedpkg clone <package_name>
- If you update to a new upstream version, you have to upload the tarball to an external lookaside cache. Operations on the lookaside cache require a client-side certificate, to get one, run:
Edit your spec file manually to bump up the version or use
spectool -g package_name.spec to get the new upstream source instead of using wget or other means. That way you make sure that the URL specified in the spec file is current. To upload a new source tarball and replace an older one, in the branch directory (i.e. devel in this case) run:
fedpkg new-sources /path/to/package_name.tar.gz
or for multiple files:
fedpkg new-sources package_name.tar.gz package_name_tests.tar.gz
You can omit the path if the source is the current directory.
This also updates your local copy of the .gitignore and sources files. You will need to do this for each branch that you will be building the new version for, or alternatively you can merge the master branch in the other branches. The new tarball will be uploaded only once and the rest will be md5sum checked and not uploaded, only the .gitignore and sources files will be updated.
If you just want to add another tarball (e.g. a big gzipped patch or a documentation tarball), use:
fedpkg upload somefile.tar.gz
fedpkg new-sources, this does not purge old files from the
If you just have a small patch or otherwise plain text file, you can commit those directly to git. This can be done with the
git add command, e.g.:
fedpkg add packagename-fix-the-foobar.patch
- Use the command
fedpkg mockbuildto test a package build on your local mock system. Then install and test the package. If something doesn't work, fix it and repeat this step. You can also use the koji build system to do a scratch build perhaps for some arch you don't have locally. For example, to build just for x86_64:
fedpkg srpm koji build --scratch --arch-override x86_64 f18 packagename-version-release.src.rpm
- Check if everything that has changed is correct with the first command which shows diff of the change and the second command runs rpmlint against your spec file, srpm and binary RPMs to verify that it complies with packaging guidelines:
fedpkg diff fedpkg lint
- Add any changes you made to the spec:
git add package_name.spec
- Generate Git commit from spec changelog, commit to devel branch and push in one go:
fedpkg commit -p -c
- Do the above steps one by one
fedpkg clog fedpkg commit -F clog fedpkg push
As a test whether the full commit was fine, you can check out a fresh working copy into a different directory. It should succeed in fetching the binaries from lookaside cache and also pass simple build tests such as make i686 or make srpm at least.
- Finally, instruct the builders to build your package for rawhide:
- Check the koji build page at http://koji.fedoraproject.org/koji/ for the build process.
fedpkg clone foo cd foo spectool -g foo.spec fedpkg new-sources foo-0.0.2.tar.bz2 gedit foo.spec # change the required things in the specfile. rpmdev-bumpspec is useful for simple version updates fedpkg mockbuild # check that the changes you made are correct fedpkg diff fedpkg lint fedpkg commit -p -c # commit and push in one go
# request build fedpkg build
The package builders publish your package in the
development tree, also called "Rawhide." If the package is a stable update, you may also provide it to users of the currently-maintained stable, or branched Fedora release. To make it available to F-19 or F-20 users, or testers of the branched F-21 for example, use the procedure outlined in the next chapter.
An alternative may be used, the import of a complete src.rpm.
More in-depth information on the build system is at UsingKoji.
Removing a package build from the devel branch
From time to time you may want to remove a package build you pushed to the devel branch (rawhide). 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. You may want to wait for this release instead of back-porting a fix yourself, so pulling the broken package from rawhide makes sense.
You can remove the package from rawhide by using koji as follows:
koji untag-pkg f20 foo-1.1.3-1.fc20
foo-1.1.3-1.fc20 is replaced with the name of your package build. See
koji help or UsingKoji for more information.
When updating a package affects a large number of dependencies (e.g. all perl, python, ruby or ghc packages) it may be better to initially do the builds in another repo, so that there is less disruption in rawhide.
If you think you have an update that falls under this case you can request a special dist tag by filing a release engineering ticket. Someone from release engineering will likely want to discuss your needs to make sure this is really an appropriate case (it's OK ask if you aren't sure) and that you get what you need.
Working with packages in the stable branches
Stable branches are branches within git for either released Fedoras, or a branched Fedora that is still in bugfix/polish mode but has not yet been released.
- Switch to the branch which you would like to update with the
fedpkg switch-branchcommand. Here is an example of an update for Fedora 20:
fedpkg switch-branch f20
- Make any required changes. In many cases, you can apply the same changes from the
devel/branch to the other branches. Use the
patchutilities for this purpose.
- Use the command
fedpkg localto test a package build on your local system. Then install and test the package. If something doesn't work, fix it and repeat this step.
- Commit the verified changes to the branch you are working on:
git push. Example of
git push origin f20:refs/heads/f20/master. See also Fedora branch names.
- Instruct the builders to build your package:
- Check the koji build page at http://koji.fedoraproject.org/koji/ for the build process.
- If you want to build a package for the Pending Fedora 21 but it requires package that is not yet pushed "stable" for Fedora 21.
- You would need to file a buildroot override tag request as outlined in the policy page Alpha_Freeze_Policy
- Once tagged, you can proceed to build her package and issue the Bodhi request
Submit your update to Bodhi
- This can be accomplished in a few different ways. The easiest being:
fedpkg update. If your local username differs from that of your Fedora account, you will need to specify it with the following command:
BODHI_USER=foo fedpkg updateOr you add
export BODHI_USER=footo the file
~/.bashrcand run the following command:
source ~/.bashrc fedpkg update
- Once submitted, bodhi will automatically request that your update be pushed to updates-testing. Note that security updates follow a slightly different process .
- A Release Engineer then signs and pushes out your updates. The signing step is currently a manual process, so your updates will not be instantly released once submitted to bodhi.
- Once pushed to testing, people are able to +1/-1 the updates "karma", based on whether or not it seems to be functional for them. If your update reaches a karma of 3 (default value, changeable before pushing out an update), it will automatically be pushed to stable. Likewise, if it reaches -3 (default valie, changeable before pushing out an update), it will be automatically unpushed. If your update does not receive enough feedback to automatically push it to stable, you will have to submit it as a final update yourself. This can easily be done with the command-line tool, or with the web interface.
- You will then be notified when your update has been pushed to stable. Bodhi will close all associated bugs and send an announcement to fedora-package-announce. At this point, your update has been officially released!
Consider Creating a Package Test Plan
If you create wiki page containing a test plan for your package, and categorize it appropriately, it will be automatically linked in Bodhi, so that testers will have guidance about what to do to make sure a package update is okay.
Details on creating a test plan are found at QA:SOP_package_test_plan_creation]].
Get Automatically Notified on New Upstream Releases
To automatically get notifications via bugzilla whenever upstream has a new release, refer to upstream release monitoring page.