Wikis are not just for encyclopedias and websites anymore. You can use Ikiwiki in combination with your revision control system to handle issue tracking, news feeds, and other needs of a software project. The wiki can make your bug reports as much a part of your software project as its code, with interesting results.

Ikiwiki is a wiki engine with a twist. It's best described by the term "wiki compiler". Just as a typical software project consists of source code that is stored in revision control and compiled with make and gcc, an ikiwiki-based wiki is stored as human-editable source in a revision control system, and built into HTML using ikiwiki.

Ikiwiki uses your revision control system to track changes and handle tasks such as rolling back changes and merging edits. Because it takes advantage of revision control, there are no annoying warnings about other people editing a file, or finding yourself locked out of a file because someone else started editing it and left. Instead, the other person's changes will be automatically merged with yours when you commit.

In the rare cases where automatic merging fails because of concurrent edits to the same part of a page, regular commit conflict markers are shown in the file to let you resolve the conflict, as you would for conflicting edits in source code.

Ikiwiki is a full-featured wiki that you can use for a variety of purposes, from traditional wikis to weblogs, podcasting, or even aggregating other sites' RSS feeds into a Planet page. While people are using Ikiwiki for purposes ranging from genealogy research to shoe accessory sales, one thing it's especially well suited for is collaborative software development, including announcements, documentation, managing a software project's web site, and even acting as an issue tracking system.

Building a project wiki with ikiwiki

The simplest way to use ikiwiki is to build static HTML files from source wiki files. This example builds a wiki for an imaginary software project. The wiki source files used in this example are available in the examples/softwaresite section of ikiwiki's documentation.

wiki$ ls
Makefile  bugs.mdwn     doc/      download.mdwn  news/
bugs/     contact.mdwn  doc.mdwn  index.mdwn     news.mdwn
wiki$ make
ikiwiki `pwd` html --wikiname FooBar --plugin=goodstuff \
    --exclude=html --exclude=Makefile
wiki$ w3m -dump html/doc/faq.html
FooBar/ doc/ faq

FooBar frequently asked questions.

1. Is this a real program?
2. Really?

_Is this a real program?_

No, it's just an example.

_Really?_

Yes, really.

Links: contact doc
Last edited Wed Nov 22 09:58:35 2006

If all you need is a simple static set of pages that can be put up on a web site, or shipped with a software package, this is a good starting point. The examples included with ikiwiki include pages for a news feed for the project (with RSS), an issue tracker, and other pages users expect to see on a project's website. You can check the wiki-format text into revision control as part of the software project, and tie it into the build system using the Makefile.

Ikiwiki can also be tied into the post-commit hook of your revision control system, so that whenever a developer commits a change to a wiki page in revision control, the project's web site is automatically updated. The ikiwiki tutorial explains in detail how to set this up using the Subversion, Git, TLA, and Mercurial revision control systems.

The tutorial also explains how to configure ikiwiki so that users can edit pages using a web interface, with their changes committed back into revision control. After all, one of the benefits of keeping a project's docs in a wiki is to make it easy for users to improve them, so that busy software developers don't have to. And if the wiki is being used for issue tracking, this will let users post and follow up on bug reports.

Using a wiki for issue tracking?

You might be wondering exactly how a wiki can be used as an issue tracking system. Three key parts of ikiwiki come together to create an issue tracker: pages, tags, and inlining.

Each issue is described on a separate page in the wiki. There can also be an associated Discussion page, as well as other related subpages that can be used to hold files used to reproduce the bug, or patches, or other related files. Since each issue is a page, standard wiki links can be used to link related issues, or link issues with other pages in the wiki. Each issue has its own unique URL. Since ikiwiki supports subdirectories, it's usual to keep all the bugs in a bugs/ subdirectory. You might prefer to separate bugs and todo items, with todo items in their own 'todo/' subdirectory.

While directories are useful for broad hierarchical grouping, tags are better for categorizing issues as bugs, wishlist items, security issues, patches, or whatever other categories are useful. Bugs can be tagged "moreinfo", "done", "unreproducible", etc, to document different stages of their lifecycle. A developer can take ownership of a bug by tagging it with something like "owner/Joey".

To tag a wiki page, edit it and add text such as "[[!tag done]]". Note that adding a wiki link to "[[done]]" will have the same categorisation effect as a tag, but the link will show up in the body of the page, which is a nice effect if used in a sentence such as "This was [[done]] in version 1.1.". Another way to close a bug is to move it out of the bugs/ subdirectory, though this would prevent it from showing up in a list of closed bugs.

Inlining is how ikiwiki pulls individual issue pages together into something larger, be it a page listing recently opened bugs (with a form to let a user easily post a new bug), or a page listing recently closed bugs, or an index of all bugs, or all wishlist items, or RSS feeds for any of these. A flexible syntax is used for specifying what kind of pages should be inlined into a given page. A few examples:

• A typical list of all open bugs, with their full text, and a form to post new bugs.

  [[!inline  pages="bugs/* and !link(done) and !*/Discussion" actions=yes postform=yes show=0]]
  

• Index of the 30 most recently fixed bugs.

  [[!inline  pages="bugs/* and link(done) and !*/Discussion" sort=mtime show=30 archive=yes]]
  

• Index of the 10 most recently active bugs.

  [[!inline  pages="bugs/* and !link(done) and !*/Discussion" sort=mtime show=10]]
  

• Open security issues.

  [[!inline  pages="bugs/* and link(security) and !link(done) and !*/Discussion"]]
  

• Full text of bugs assigned to Joey.

  [[!inline  pages="bugs/* and link(owner/Joey) and !link(done) and !*/Discussion" show=0]]
  

It may seem strange to consider using a wiki for issue tracking when there are several dedicated bug tracking systems, like Bugzilla, that handle all aspects of it already. The weakest part of using ikiwiki for issue tracking, and certainly the place where a dedicated bug tracker like Bugzilla shines in comparison, is storing and querying structured data about bugs. Ikiwiki has little structured data except for page filenames and tags, so if you need lots of queryable data such as what versions a bug affects and what version it was fixed in, ikiwiki may not be a good fit for your issue tracking.

On the other hand, by using a wiki for issue tracking, there is one less system for users and developers to learn, and all the flexibility of a wiki to take advantage of. Ikiwiki even supports OpenID, so it's easy for users to use it for filing bugs without going through an annoying registration process.

Developers who work offline, or at the other end of a slow connection, might appreciate having a full copy of the project bug tracking system, too.

Benefits

Realistically, there are plusses and minuses to letting users edit a software project's documentation in a wiki. Like any wiki, to be successful, some review is needed of the changes users make. In some cases it will be easiest to limit the pages that users are allowed to edit. Still, keeping the wiki open for user edits will probably turn up some passionate users who prove very useful at filling in holes in the documentation f="../local.css" type="text/css" />

function fixLinks() {
  var scheme = location.protocol;
 if (scheme=="http:" || scheme=="https:") return;
 var links = document.getElementsByTagName("a");
  for (var i = links.length; --i >= 0; ) {
   var link = links[i];
    var href = link.href;
    var hlen = href.length;
   if (hlen > 0 && link.protocol==scheme && href.charAt(hlen-1) == "/")
     links[i].href = href + "index.html";
  }
}

<html>
<head>
<script language="JavaScript">
function fixLinks() {
...
}
</script>
</head>
<body onload="javascript:fixLinks();">
...
</html>