Expanding wiki templates inside <pre>

I tend to do a fair amount of wiki work these days. Whether it’s scripting against the mediawiki api, or just manually editing pages … you tend pick up little tips here and there. One such gem I’ve been using for a while is to get mediawiki templates to expand when used inside preformatted <pre> tags.

Why bother? Well, when writing test cases, or related pages, I frequently provide command-line samples or output. I like to ensure that the output remains relevant over time. Even more, I dislike having to frequently update a page release after release to ensure the commands or output are still relevant. For some common QA-related <pre> tag examples, checkout the following links …

• How to update AutoQA repoinfo.conf – provide copy and paste-able configuration files used whenever a Fedora release branches or reaches end-of-life.
• QA:SOP Installation Test – Provides a sample command-line script to count test day participants.
• QA:Testcase Anaconda save traceback to bugzilla – Specify boot arguments for various installer traceback tests

Okay, you get the idea. The fun part is hidden in the first example. What if you want to take advantage of some awesome wiki templates, such as {{FedoraVersion}}? If you try that … the <pre> tags will show you just that … pre-formatted text as shown below.

mock -r fedora-{{FedoraVersion||previous}}-x86_64 --init 

If you like puzzles, and are hell-bent on having templates expansion inside <pre> tags, let me save you a tremendous waste of time searching for the correct solution. … To expand mediawiki templates inside <pre> tags … you can use a miscellaneous parser function. The function is a bit strange, but works as follows …

{{#tag:pre| 
mock -r fedora-{{FedoraVersion||previous}}-x86_64 --init 
}}

The above syntax will produce the following wiki output …

mock -r fedora-14-x86_64 --init 

All that to emit two characters! I know, but I’m lazy and this solution helps me to never update that particular wiki page ever again. It will always point to the proper release thanks to Template:FedoraVersion. Also, thanks to a post from Das Gurke on the Customizing-MediaWiki mwusers forum for pointing out the right answer.

If you have other creative uses for the #tag:tagname parser function, please share!

Fedora 15 QA retrospective

It’s that time again.  Time to review, discuss and learn from any hiccups encountered while testing the previous release.  No matter how successful a release is, there is always something to improve on.  Fedora 15 was no exception.

First, some ground rules … we’re not trying to solve the world problems with this retrospective.  It’s focused on Fedora QA, our interactions with other teams, and what we can improve on to better accomplish our goals.  For a more general release retrospective, Jared already has an app for that.  Next, this isn’t the place to point fingers and taunt other teams/people.  Use your own blog for that :).  Let’s keep the retrospective as objective and actionable as possible.  For example, when recording issues, it’s important to know the bug(s) involved and what factors contributed to the problem(s).  I’m not interested in what Steve thinks Mary said that Jillian heard after passing out at 31 flavors last night.

Next, a bit of history.  The process starts early each release when I draft a retrospective wiki page to track issues as they happen.  I break the page down into three groups; 1) what worked (sometimes we get things right!), 2) what didn’t work (learn from our mistakes etc…), 3) wishlist (aka pony).  It’s just my nature to want to know what went wrong, and try to fix it.  Accordingly, most of the content focuses on problems we encounter during the release.  Also, I wanted to have some concept of scope … which is where the wishlist/pony group comes in.  I still don’t know if it really fits, but I find it interesting to see what comments people have without constraints.

The retrospective concept doesn’t really work if only one person provides feedback.  So, I try to get the word out so anyone can add issues.  This is an area where I could certainly do better, probably by blogging more about it.  As the release progresses, I beg/plead/nag people closest to the issues to add some notes to the wiki.  I’m sure most people get tired of my nagging for content, but I’ve seen too often where we forget the causes of a critical problem, or don’t properly record the conditions leading up to a failure.  Without accurate data on the cause of problems, any corrective measures are just busy work.  So, the release chugs along, and hopefully the list of good/bad/wishlist issues matures.

mental note … I need to document this in a SOP

Okay … so all that preamble just to let folks know I completed a draft of recommendations based on the Fedora 15 QA retrospective feedback.  I’ll be sending this out to the test@ list for review shortly.  Check it out, and tell me what you think.  See something missing, don’t agree with something … just let me know.

Image by Camilo via flickr used under a Creative Commons license.

 

{{Key_press}}

If you haven’t heard me say it before … “I really like media wiki.”  It’s tremendously flexible, clearly very well-used and maintained, and as there is an abundance of useful content on mediawiki.org. If you are trying to do something on the wiki, chances are someone has already done it.

For example, displaying test results on the wiki (refer to {{Result}}).  While this was started by Will Woods, it later adapted based on experiences with templating on OLPC’s wiki.  Also adapted from OLPC’s wiki is our use of {{QA/Test_Case}}.  Finally, as Athmane recently pointed out, I borrowed {{!}} and {{=}} from mediawiki so you can make use of those characters when using a template.  Who cares?  Well, if you’ve ever attempted to write an admonition (e.g. {{admon/warning}}), you may have noticed it doesn’t format properly when you include certain characters (notably = and | which have special meaning in mediawiki template syntax).

Without “escaping” the special characters, your template will render improperly as seen below …

{{admon/warning|Warning!|Sometimes a=b and b=c. 
In that case, a=c. :-| }}

This doesn't look correct.

This can be corrected by using the {{!}} and {{=}} templates, as shown below.

{{admon/warning|Warning!|Sometimes a{{=}}b and b{{=}}c. 
In that case, a{{=}}c. :-{{!}} }}

Much better!

Today I found another really helpful series of templates for something I’ve wanted for a long time.  In Fedora QA, we write and maintain a lot of test cases on the wiki.  Often in a test case, one describes a series of steps, or procedure, to perform a particular function in a specific manner.  We extensively use <pre>, lists (both forms # and <ol>) and helper templates such as {{filename}}, {{package}} and {{command}}.

It’s always bugged me that we didn’t have a consistent, and visually striking manner for representing keyboard events.  For example, telling a tester to … “Hit <code>Ctrl-Alt-Backspace to stop Xorg” ([1]) just doesn’t stand-out to me enough.  What can I say … I’m a visual person.  I stumbled upon an awesome series of templates from mediawiki.org for displaying key combinations.  Enter … {{Key_press}}.  With the help of many smaller templates, I’ve added this support, along with the rock solid “upstream” documentation, to the fedoraproject.org Wiki.  I’m not sure who to thank for the template, as there are a significant number of editors.

So instead of something like  …

# Activate the overview by pressing the Windows key,
 pressing <code>Alt-F1</code>, or by moving the mouse
 to the top-left corner of the screen.

One can write …

# Activate the overview by pressing the 
 {{key press|Win}} key, pressing {{key press|Alt|F1}},
 or by moving the mouse to the top-left corner of the
 screen

Which results in something my brain responds to much better…

From my docbook XML days, I appreciate structured ways to write content and separation between content and the look’n’feel.  However, I dislike editing content in XML.  Templates like {{command}}, {{filename}} and now {{Key_press}} offer a ways to accomplish the same thing with mediawiki.  I plan to use this more when documenting keyboard events in future test cases.  Hopefully, someone else finds this useful as well.

PreUpgrade Test Day this Thursday (2011-03-17)

Have you seen this dialog?  It’s from a pretty handy utility called preupgrade.  Preupgrade takes some of the complexity out of upgrading your Fedora system.  But like any software, to keep running smoothly, it needs testing and maintenance.

For the past several releases, Fedora QA has hosted several test days (F14 and F13) to shake out bugs related to system upgrades using the preupgrade tool.  Those same tests are also included in our regular release validation matrix.  I’d like to think that regular, organized testing of preupgrade (and installer upgrades) contributes to a more reliable upgrade experience once Fedora GA’s.  Thanks to Hurry for helping to organize these events. 🙂

Testing involves performing system upgrades using the latest preupgrade package.  There are test instructions (including test cases) on the wiki page.  Fedora QA and Richard Hughes (preupgrade maintainer) will be in the IRC channel #fedora-test-day on Freenode all day to help with testing and answer any questions you might have.  If you’re not familiar with IRC, a web-based (WebIRC) client is available.

To participate, you’ll need a Fedora 14, or Fedora 13 system ready for upgrade.  Test systems can be bare metal or virtualized guests, it doesn’t matter.  If you don’t have a previous release handy, don’t worry … live images for previous releases are a great way to quickly install a working desktop.

Unfortunately, preupgrade doesn’t test itself, so we need your help.  This is a good chance to get a head start on Fedora 15 Beta testing, and help identify preupgrade-related bugs early.    See you on Thursday!