FESCo docs have moved to docs.fp.o with source hosted in a pagure repo. This page is now at https://docs.fedoraproject.org/en-US/fesco/Mass_package_changes/.
From time to time changes are required across a group of packages. When the changes are complex or the number of affected packages is large, coordination is absolutely required to avoid confusion and wasted effort. The mass filing of bugs may be required, which must be done with care. This page attempts to describe some steps to take when mass changes are needed and to outline the procedure for a mass bug filing in the event that it is necessary.
Everyone is busy, and package maintainers are often volunteers. Many maintainers also receive far too much email from bugzilla, so additional bugs are often not desired. A little extra effort up front can result in a smoother process for everyone, even though this can take a little longer. And often an actual mass bug filing can be avoided.
Gain consensus of needed changes
First you should post to the Fedora devel list and gain consensus for the changes you want to make. No matter how simple or needed you might think they are, there may be better ways to do things or the change may not be needed for other reasons. Part of this discussion should be the development of a concise set of instructions which packagers will need to follow in order to fix the affected packages. This can of course refer to external documents but packagers should be able to get the basic idea of what changes are needed without having to chase down links.
Indicate the packages which need to change
The set of packages which will need changes should be posted to the devel-announce list as soon as that set has been determined. To make things as easy as possible on the maintainers involved, this should take the form of two lists, one listing packages and their owners, and the other listing maintainers and their packages. This makes it trivial for a single maintainer to see how much work there is to do, and also for others to have an idea of who might need help. For convenience, a utility which will generate these lists given a file of package names is available from https://pagure.io/fedora-misc-package-utilities/ as "find-package-maintainers".
These lists should be updated throughout the discussion as packages are fixed, and should also include the instructions for fixing the packages mentioned above.
Automated cleanup
Automated package cleanup is encouraged. If it is possible to make the relevant change in an automated fashion with a low chance of unwanted side effects then this should at least be considered, even if that can only be done for a subset of the affected packages. The actual details of this process (such as whether builds are required or if the changes should simply be committed) are almost certainly dependent on the changes involved and should be worked out during the discussion. Proven packagers may perform automated cleanup without using pull requests by pushing directly to source control.
Review announcement / bug text
Either ask the list or several interested maintainers to look over the text you intend to send to the devel-announce list (next step) and intend to use in your bug text. This will help make your text clear and understandable and free from typos or other simple errors. Make sure several people see your text and agree it describes the problem clearly along with solutions. This text should include the instructions developed above.
Announce to devel-announce
Once you have a clear idea of the changes needed, post a clear email on changes needed to the devel-announce list. Wait at least a week to allow maintainers to make changes or ask you further questions about the change on the devel list. If the change must be done due to some deadline, please note it in the email. If you intend to have provenpackager(s) or an automated process simply make the changes to all unchanged packages, please note that as well in the email.
File tracker bug
Now you can file a tracker bug in bugzilla and bugs against all the packages that still need changes. Note that you should check to make sure maintainers didn't already make the changes and only file bugs against those packages that didn't.
Things to note in bugs
- Make sure you note what releases you consider must be fixed, or if only rawhide is fine.
- Note if you wish updates to be submitted simply for this change, or if the change can be pushed the next time there is another reason to update.
- Link to the specific wiki page or guideline that is affected.
- If the change is small, please include what the maintainer needs to add or remove specifically from their spec.
- If the change is large, please include a summary of what changes are needed. A link to an external page with complete documentation is of course necessary, but a packager should be able to obtain a basic understanding of the change from what is included in the bug itself. A link to a mailing list discussion is simply not sufficient.
- Note the announcements and any mailing list threads where the change has been discussed.
- Note any deadlines beyond which provenpackagers might step in and make changes.
- Note where maintainers can provide feedback or ask for more information if the bug is unclear.
- Include the name of the package in the summary line of each child bug, so that it is possible to quickly see the affected components in the tree view.