Skip Links

Network World

  • Social Web 
  • Email 
  • Close

(Comma separation for multiple addresses)
Your Message:

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,
April 06, 2007 01:20 PM ET
  • Share/Email
  • Tweet This
  • Comment
  • Print

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.

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.


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 Web site. 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.

  • Share/Email
  • Tweet This
  • Comment
  • Print
Our Commenting Policies
Latest News
rssRss Feed
View more Latest News