Common bugs instructions

In other languages: English (en) español (es) [edit]

When adding a bug to one of the Common Bugs pages, it is best to follow these instructions. Using the standard format and templates improves the readability and quality of the pages.

Bugzilla metadata

Whenever you add an entry which covers a bug listed in Bugzilla, please set the CommonBugs keyword for the bug, and add a link to the Common Bugs page entry to the bug's Whiteboard field.

Entries for resolved bugs

Once an issue has been resolved, add the {{Common bugs update released}} template that links to the update (see below for more details). If the issue appeared in a pre-release (Alpha or Beta), once the next milestone build is released (Beta or Final), you can remove the entry from the page entirely. For stable releases, the entry should never be removed, but should be moved to the Resolved issues section.

Bug entry format

Use the issue template at the top of your entry. This creates the anchor link, section heading, and bugzilla links. The format is:

{{Common bugs issue|broken-foo|Foo breaks when you do bar|1234567|7654321}}

Here is what that input produces:

Foo breaks when you do bar

link to this item - Bugzilla: #1234567 - Bugzilla: #7654321

Note the first parameter, broken-foo in our example, is used as the "link to this item" anchor link - make it short but unique, and don't use special characters, to keep the link text nice and clean.

If there is an update available to fix the bug, add another template right under the header. If the update is in updates-testing, use this template. If the update is stable, use this one - and put your issue in the Resolved issues section of the page. Both templates take just one parameter, the update's advisory ID, which you can see on the update's Bodhi page. It will be something like FEDORA-2014-16304. So:

{{Common bugs update testing|FEDORA-2014-16304}}
{{Common bugs update released|FEDORA-2014-16304}}

Here is the output from the first:

Update available for testing
A candidate fix for this issue has been submitted to the updates-testing repository for testing. Users experiencing this problem are encouraged to test this update and report to Bodhi whether it solves the problem. To test the update, run this command: sudo dnf --enablerepo=updates-testing update --advisory=FEDORA-2014-16304

And from the second:

Fix released
An update has been released to address this problem. After you update your system in your usual way, and possibly reboot, you should no longer be affected by it.

The installer is a special case. Regular package updates can't fix installer bugs, but there is an update image mechanism. If an updates image is made available for an installer bug, you can use this special template. It takes the URL of the updates image as its parameter:

{{Common bugs update anaconda|https://dshea.fedorapeople.org/1170275.img}}

Here's what you get when you use it:

Updates image available
An installer update image has been made available which resolves this issue. To use it, hit e or Tab ⇆ on the installer boot menu to edit the boot options, and add the following: inst.updates=https://dshea.fedorapeople.org/1170275.img

Finally, add some text describing the issue. So to put it all together, you might write something like:

{{Common bugs issue|broken-foo|Foo breaks when you do bar|1234567|7654321}}
{{Common bugs update testing|FEDORA-2014-16304}}
Due to leaves on the track, when you issue the 'bar' command,
foo will break, leaving a mess all over your system's nice clean floors.
To work around this, we recommend using {{command|bar2}} instead, or
putting down a plastic sheet.

And we can see how that would look:

Foo breaks when you do bar

link to this item - Bugzilla: #1234567 - Bugzilla: #7654321

Update available for testing
A candidate fix for this issue has been submitted to the updates-testing repository for testing. Users experiencing this problem are encouraged to test this update and report to Bodhi whether it solves the problem. To test the update, run this command: sudo dnf --enablerepo=updates-testing update --advisory=FEDORA-2014-16304

Due to leaves on the track, when you issue the bar command, foo will break, leaving a mess all over your system's nice clean floors. To work around this, we recommend using bar2 instead, or putting down a plastic sheet.

commonbugs-update tool

There is a tool that helps with adding 'update available' notes to bugs already listed on existing Common Bugs pages, called commonbugs-update. It can be found in the qa-misc git repository:

git clone https://pagure.io/fedora-qa/qa-misc.git

Run it with:

./commonbugs-update NN

where NN is the release number whose page you want to update.