|
|
| (40 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| This document shows how to submit an update for a package you maintain in Fedora. It assumes you already have a package in the Fedora repositories. It is not a guide to using the Fedora package source control system: see the [[Package maintenance guide]] for that.
| | {{admon/warning |This page has been moved out of the wiki. The current version of this document is located at https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/ Please update your bookmarks.}} |
| | |
| * For details of the policy on requirements for updates at various stages of the [[Fedora Release Life Cycle]], refer to [[Updates Policy]].
| |
| | |
| == Overview ==
| |
| | |
| This page is intended for new and existing package maintainers. Testers and regular users may be interested in the [[QA:Updates_Testing|updates-testing]] repository and the [[QA:Update_feedback_guidelines|update feedback guidelines]]. This page specifically covers the update submission process.
| |
| | |
| There are two significantly different package update submission workflows in Fedora:
| |
| | |
| * [[Releases/Rawhide|Rawhide]], and [[Releases/Branched|Branched]] up to the [[Updates Policy#Bodhi enabling|Bodhi enabling point]]
| |
| * [[Releases/Branched|Branched]] releases after the Alpha change deadline, and stable releases
| |
| | |
| The repository layouts differ somewhat for Rawhide, Branched and stable releases, but the update workflows split up as described above.
| |
| | |
| == Rawhide and early Branched ==
| |
| | |
| The package update workflow for Rawhide and Branched before the ''Bodhi enabling point'' is simple:
| |
| | |
| # Build the package with {{command|fedpkg build}} (see the [[Package maintenance guide]] for more details)
| |
| | |
| This is all you need to do. Your package will appear in the next daily compose of Rawhide or Branched and will be used in any image composes built from that tree. | |
| | |
| == Later Branched and stable releases ==
| |
| | |
| At the [[Updates Policy#Bodhi enabling|Bodhi enabling point]], the [[Bodhi]] update feedback system is enabled by [[ReleaseEngineering|Release Engineering]] and builds submitted with {{command|fedpkg build}} are no longer automatically sent to any official [[Repositories|repository]]. The update workflow for releases of this type is:
| |
| | |
| # Build the package with {{command|fedpkg build}}
| |
| # Submit an update for the package with {{command|fedpkg update}} or via the [https://admin.fedoraproject.org/updates/ Bodhi web interface]. This causes the package to be sent to the [[Repositories#updates-testing|''updates-testing'']] repository
| |
| # After the update meets the criteria in the [[Updates Policy]], submit the update to ''[[Repositories#stable|stable]]'' with {{command|bodhi -R stable}} or the web interface
| |
| | |
| {{admon/important|Updating inter-dependent packages|If a package you wish to update requires other package(s) to be rebuilt before it or they will work properly, you '''must''' submit the builds together as a multi-package update. See [[#multi|below]] for more details on this.}}
| |
| | |
| At the time you submit the update, you may set a ''karma'' (feedback) level at which the update will automatically be submitted to ''stable''. This is optional. If you choose to use it, please carefully consider an appropriate feedback level. For a relatively obscure package which is quite stable, 1 or 2 may be an appropriate value. For a popular, sensitive and complex package such as {{package|firefox}} or the {{package|kernel}}, the default of 3 may be insufficient and a choice of 5 or even 10 may be appropriate.
| |
| | |
| When a release is in Branched state, the ''updates-testing'' repository is enabled by default so most users will see the package, but only packages from the stable ''fedora'' repository are used in building milestone releases (Alpha, Beta and Final) and nightly images.
| |
| | |
| Where a package goes when it is marked as ''stable'' differs between Branched and stable releases. In Branched releases, ''stable'' packages are pushed to the base ''fedora'' repository. In stable releases, ''stable'' packages are pushed to the ''updates'' repository. However, from the point of view of the packager, this is an insignificant implementation detail. For more details, see [[Repositories]].
| |
| | |
| When a release is in stable state, the ''updates-testing'' repository is disabled by default, but [[QA]] team members and others run with it enabled in order to provide testing and Bodhi feedback. The main user population will see your update only when it passes Bodhi, is marked as ''stable'' and reaches the ''updates'' repository.
| |
| | |
| {{anchor|multi}}
| |
| === Updating inter-dependent packages ===
| |
| | |
| If an update you wish to submit would cause a dependency issue of any kind (a strict package dependency error, or simply another package failing to operate correctly) if updated alone, you must not submit the package as a single-package update. You must always collect all inter-dependent or related packages together into a single multi-package update, such that no user will face problems if they install all the packages in the update together.
| |
| | |
| For example: if you maintain a package ''libfoo'' which the package ''bar'' depends on, and you need to update ''libfoo'', you should check that ''bar'' continues to function correctly with the updated version of ''libfoo''. If it does not, you must ensure the appropriate changes are made to ''bar'', and include the updated ''bar'' in your update along with the updated ''libfoo''.
| |
| | |
| The ''fedpkg'' tool does not handle multi-package updates. You can add multiple packages to an update using the [https://admin.fedoraproject.org/updates/ Bodhi web application], or the {{command|bodhi}} command line tool. You can pass as many package names as you like to the {{command|bodhi --new}} to create a new multi-package update, or use {{command|bodhi --edit}} to edit an existing update.
| |
| | |
| It is possible you will run into problems with permissions when trying to add builds of packages you do not have commit privileges for to an update, or trying to add a build for a package you do have privileges for to someone else's update. If you encounter a situation like this, you should contact the [[ReleaseEngineering|release engineering]] team for help.
| |
| | |
| You may need a ''buildroot override'' to complete a multi-package update successfully. For instance in the case described above, you may need to rebuild ''bar'' against the new ''libfoo'' package and submit both packages together as a multi-package update. However, in the normal course of events, you would not be able to build another package against your new ''libfoo'' build until it reached the [[Repositories#stable|''stable'']] state. To resolve this dilemma, you can request a buildroot override, which causes the ''libfoo'' build to be included in the buildroot for a short time in order to get the ''bar'' package build done.
| |
| | |
| You can request a buildroot override with bodhi: {{command|bodhi --buildroot-override<nowiki>=</nowiki>(name-version-release) --duration<nowiki>=</nowiki>2 --notes<nowiki>=</nowiki>"Useful details."}} This would submit a buildroot override with a duration of two days. Buildroot overrides are usually granted within 15-30 minutes of submission. If you submit an override request with the bodhi tool, it will suggest a command that will let you monitor when the package appears in the buildroot, so you can fire your dependent build at the appropriate time.
| |
| | |
| You can also request buildroot overrides from the [https://admin.fedoraproject.org/updates/ Bodhi web application].
| |
| | |
| The [[Bodhi/BuildRootOverrides|buildroot override instructions]] explain the buildroot override process in more detail.
| |
| | |
| === Branched milestone freezes ===
| |
| | |
| For a short period before each milestone release, the stable [[Repositories#fedora|''fedora'']] repository is frozen. These periods are shown as the [[Milestone freezes]] (Alpha Freeze, Beta Freeze, Final Freeze) on schedules. During these periods, builds will not be marked ''stable'' and pushed from [[Repositories#updates-testing|''updates-testing'']] to ''fedora'' even after being submitted manually or automatically. In the normal course of events, they will be pushed after the milestone release is approved at a [[Go_No_Go_Meeting]]. If you believe your update deserves to break a milestone freeze, a ''freeze exception'' may be granted through the [[QA:SOP_freeze_exception_bug_process|freeze exception process]]. Accepted release blocking bugs are granted the same status through the [[QA:SOP_blocker_bug_process|blocker bug process]].
| |
| | |
| For more on the Fedora development process, see [[Fedora Release Life Cycle]].
| |
| | |
| {{admon/tip|
| |
| If you are unsure whether your build is currently considered ''stable'' for a given release, you can check with {{command|koji latest-pkg fXX}} (where XX is the release).}}
| |
| | |
| == New package submissions ==
| |
| | |
| If you want to build a new package, but you aren't sure which releases to send it to:
| |
| | |
| * New packages should always be built for Rawhide
| |
| * New packages can be built for Branched and stable releases if adding them would provide value to users of those releases without significant risk of causing harm
| |
| | |
| The submission process for new packages, after they have passed the [[Package_Review_Process]] and been [[Package_SCM_admin_requests|given an SCM repository]], is exactly the same as that for package updates.
| |
| | |
| == Consider creating a package test plan ==
| |
| | |
| If you [[QA:SOP_test_case_creation|create test cases]] for your package, and [[QA:SOP_package_test_plan_creation|categorize them appropriately]], they will be automatically linked in Bodhi, so that testers will have some guidance for planned update testing.
| |
| | |
| [[Category:Package Maintainers]]
| |
