Subscribe to this site with RSS

Integrated issue tracking with Ikiwiki

Connect project documentation with bug tracking and the revision control system, using a new powerful approach to Wiki software.

By Joey Hess, LinuxWorld.com, 04/06/07

Wikis are not just for encyclopedias and Web sites 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 in which 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 edit in source code.

Ikiwiki is a full-featured wiki that you can use for a variety of purposes, from traditional wikis to blogs, 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.