1 [[!meta title="Integrated issue tracking with Ikiwiki"]]
2 [[!meta date="2007-04-06 21:36:07 +0000"]]
4 [[!meta author="Joey Hess, LinuxWorld.com"]]
7 Copyright 2007 Joey Hess <joeyh@ikiwiki.info>, LinuxWorld.com
8 [First published](http://www.linuxworld.com/news/2007/040607-integrated-issue-tracking-ikiwiki.html)
9 on [LinuxWorld.com](http://www.linuxworld.com/), a publication of Network
10 World Inc., 118 Turnpike Rd., Southboro, MA 01772.
12 [[!meta license="[[GPL|freesoftware]]"]]
14 Wikis are not just for encyclopedias and websites anymore. You can use
15 Ikiwiki in combination with your revision control system to handle issue
16 tracking, news feeds, and other needs of a software project. The wiki can
17 make your bug reports as much a part of your software project as its code,
18 with interesting results.
20 Ikiwiki is a wiki engine with a twist. It's best
21 described by the term "wiki compiler". Just as a
22 typical software project consists of source code
23 that is stored in revision control and compiled with
24 `make` and `gcc`, an ikiwiki-based wiki is stored as
25 human-editable source in a revision control system,
26 and built into HTML using ikiwiki.
28 Ikiwiki uses your revision control system to track
29 changes and handle tasks such as rolling back changes and
30 merging edits. Because it takes advantage of revision
31 control, there are no annoying warnings about other
32 people editing a file, or finding yourself locked
33 out of a file because someone else started editing it
34 and left. Instead, the other person's changes will
35 be automatically merged with yours when you commit.
37 In the rare cases where automatic merging fails
38 because of concurrent edits to the same part of a
39 page, regular commit conflict markers are shown in
40 the file to let you resolve the conflict, as you
41 would for conflicting edits in source code.
43 Ikiwiki is a full-featured wiki that you can use
44 for a variety of purposes, from traditional wikis
45 to weblogs, podcasting, or even aggregating other
46 sites' RSS feeds into a Planet page. While people
47 are [[using|ikiwikiusers]]
48 Ikiwiki for purposes ranging from genealogy research
49 to shoe accessory sales, one thing it's especially
50 well suited for is collaborative software development,
51 including announcements, documentation, managing a
52 software project's web site, and even acting as an
53 issue tracking system.
55 ## Building a project wiki with ikiwiki
57 The simplest way to use ikiwiki is to build static
58 HTML files from source wiki files. This example builds
59 a wiki for an imaginary software project. The wiki
60 source files used in this example are available in the
61 [[examples/softwaresite|examples/softwaresite]] section
62 of ikiwiki's documentation.
65 Makefile bugs.mdwn doc/ download.mdwn news/
66 bugs/ contact.mdwn doc.mdwn index.mdwn news.mdwn
68 ikiwiki `pwd` html --wikiname FooBar --plugin=goodstuff \
69 --exclude=html --exclude=Makefile
70 wiki$ w3m -dump html/doc/faq.html
73 FooBar frequently asked questions.
75 1. Is this a real program?
78 _Is this a real program?_
80 No, it's just an example.
87 Last edited Wed Nov 22 09:58:35 2006
89 If all you need is a simple static set of pages
90 that can be put up on a web site, or shipped with
91 a software package, this is a good starting point.
92 The examples included with ikiwiki include pages for
93 a news feed for the project (with RSS), an issue
94 tracker, and other pages users expect to see on a
95 project's website. You can check the wiki-format text
96 into revision control as part of the software project,
97 and tie it into the build system using the Makefile.
99 Ikiwiki can also be tied into the [[post-commit]] hook of your revision
100 control system, so that whenever a developer commits a change to a wiki
101 page in revision control, the project's web site is automatically updated.
102 The [[ikiwiki_tutorial|setup]] explains in
103 detail how to set this up using the Subversion, Git, TLA, and Mercurial
104 revision control systems.
106 The tutorial also explains how to configure ikiwiki so that users can edit
107 pages using a web interface, with their changes committed back into revision
108 control. After all, one of the benefits of keeping a project's docs in a wiki
109 is to make it easy for users to improve them, so that busy software developers
110 don't have to. And if the wiki is being used for issue tracking, this will
111 let users post and follow up on bug reports.
113 ## Using a wiki for issue tracking?
115 You might be wondering exactly how a wiki can be used as an issue tracking
116 system. Three key parts of ikiwiki come together to create an issue tracker:
117 pages, tags, and inlining.
119 Each issue is described on a separate page in the
120 wiki. There can also be an associated Discussion page,
121 as well as other related subpages that can be used
122 to hold files used to reproduce the bug, or patches,
123 or other related files. Since each issue is a page,
124 standard wiki links can be used to link related
125 issues, or link issues with other pages in the wiki.
126 Each issue has its own unique URL. Since ikiwiki
127 supports subdirectories, it's usual to keep all the
128 bugs in a `bugs/` subdirectory. You might prefer
129 to separate bugs and todo items, with todo items in
130 their own 'todo/' subdirectory.
132 While directories are useful for broad hierarchical
133 grouping, tags are better for categorizing issues
134 as bugs, wishlist items, security issues, patches,
135 or whatever other categories are useful. Bugs can
136 be tagged "moreinfo", "done", "unreproducible",
137 etc, to document different stages of
138 their lifecycle. A developer can take ownership of a
139 bug by tagging it with something like "owner/Joey".
141 To tag a wiki page, edit it and add text such as "\[[!tag done]]". Note that
142 adding a wiki link to "\[[done]]" will have the same categorisation effect
143 as a tag, but the link will show up in the body of the page, which is a
144 nice effect if used in a sentence such as "This was \[[done]] in version
145 1.1.". Another way to close a bug is to move it out of the `bugs/`
146 subdirectory, though this would prevent it from showing up in a list of
149 Inlining is how ikiwiki pulls individual issue pages together into
150 something larger, be it a page listing recently opened bugs (with a form to
151 let a user easily post a new bug), or a page listing recently closed bugs,
152 or an index of all bugs, or all wishlist items, or RSS feeds for any of
153 these. A flexible syntax is used for specifying what kind of pages should
154 be inlined into a given page. A few examples:
156 * A typical list of all open bugs, with their full text, and a form to post new
159 \[[!inline pages="bugs/* and !link(done) and !*/Discussion" actions=yes postform=yes show=0 rootpage="bugs"]]
161 * Index of the 30 most recently fixed bugs.
163 \[[!inline pages="bugs/* and link(done) and !*/Discussion" sort=mtime show=30 archive=yes]]
165 * Index of the 10 most recently active bugs.
167 \[[!inline pages="bugs/* and !link(done) and !*/Discussion" sort=mtime show=10]]
169 * Open security issues.
171 \[[!inline pages="bugs/* and link(security) and !link(done) and !*/Discussion"]]
173 * Full text of bugs assigned to Joey.
175 \[[!inline pages="bugs/* and link(owner/Joey) and !link(done) and !*/Discussion" show=0]]
177 It may seem strange to consider using a wiki for issue tracking when there
178 are several dedicated bug tracking systems, like Bugzilla, that handle all
179 aspects of it already. The weakest part of using ikiwiki for issue
180 tracking, and certainly the place where a dedicated bug tracker like
181 Bugzilla shines in comparison, is storing and querying structured data
182 about bugs. Ikiwiki has little structured data except for page filenames
183 and tags, so if you need lots of queryable data such as what versions a bug
184 affects and what version it was fixed in, ikiwiki may not be a good fit for
187 On the other hand, by using a wiki for issue
188 tracking, there is one less system for users and
189 developers to learn, and all the flexibility of a
190 wiki to take advantage of. Ikiwiki even supports
191 [OpenID](http://openid.net/), so it's easy for users
192 to use it for filing bugs without going through an
193 annoying registration process.
195 Developers who work offline, or at the other end of a
196 slow connection, might appreciate having a full copy
197 of the project bug tracking system, too.
202 Realistically, there are plusses and minuses to letting users edit a
203 software project's documentation in a wiki. Like any wiki, to be
204 successful, some review is needed of the changes users make. In some cases
205 it will be easiest to limit the pages that users are allowed to edit.
206 Still, keeping the wiki open for user edits will probably turn up some
207 passionate users who prove very useful at filling in holes in the
208 documentation and cleaning up the site.
210 Programmers are supposed to be bad at writing documentation, and putting a
211 project's docs into a wiki might not solve that. But it can make it a
212 little bit easier. Consider a programmer who's just coded up a new feature.
213 He can commit that to a development branch in revision control, and then go
214 update the docs on the web site to document it. But the feature isn't
215 available in a released version yet, so it's probably easier to skip
216 updating the website. Maybe once it's released, the web site will be
217 updated to mention the feature, but maybe (probably) not.
219 Now consider what happens if instead the web site is a wiki that has its
220 source included in the project's revision control system. The programmer
221 codes up the feature, and can easily update the docs in the wiki to match.
222 When he commits his changes to a development branch, the docs are committed
223 too. Later, when that change is merged to the release branch, the doc
224 changes are also merged, and automatically go live on the web site.
225 Updating the documentation to reflect each change made and publishing it on
226 the website has become a standard part of the programmer's workflow.
228 But this still requires programmers to write documentation, so maybe it
229 still won't work. Let's go back a step. Before the programmer wrote that
230 feature, he probably got some requests for it, and maybe he developed those
231 into a specification for how the feature should work. Since ikiwiki can be
232 used as an issue tracker, the requests were made using it, and were
233 collaboratively edited on the wiki, to develop the specification. Once the
234 feature is implemented, that issue can be closed. What better way to close
235 it than to move it out of the issue tracking system, and into the project's
236 documentation? In Subversion:
238 svn mv wiki/bugs/new_feature.mdwn wiki/doc/
240 If the spec is written well enough to be useful for end user documentation,
241 the programmer doesn't have to write a lot of docs after all; that was done
242 when the feature was designed. By using ikiwiki for issue tracking, plus
243 editing the spec, plus documentation, plus the website, each of these steps
244 has built on the other and the programmer has had to do less busywork.
246 A different example of how ikiwiki can tie
247 things together is how a security hole might be
248 handled. First it's discovered, and a bug filed about
249 it. When it's fixed, the commit that fixes the bug
250 can include a change to the bug's page, marking it
251 as done. Since it's a security hole, the project
252 needs to make an announcement right away so users
253 will know they need to upgrade. This announcement
254 can be added to the wiki's news feed, and committed
255 along with the fix, and the announcement can use a
256 regular wiki link to link to the bug that describes
257 the security hole in detail. If the security hole
258 also affects an older version of the software, the
259 fix, along with the wiki documentation for that fix,
260 can be merged into the branch for the older version.
262 Another benefit of keeping the bug tracking system in revision control with
263 the wiki is that it allows for disconnected development. So there's no need
264 to be online to review the project's bug list, and there's no need to
265 remember to close fixed bugs once you're back online.
267 For fans of distributed revision control, ikiwiki opens even more
268 possibilities. With a project's website and issue tracker kept in
269 distributed revision control with the project, these become distributed as
270 well, rather than centralized appendixes to the project. Developers can
271 pass around changesets that not only fix bugs, but mark them as done. If
272 large changes are being made in someone's branch, they can choose to put up
273 their own version of the website, use it to track bugs for that branch, and
274 when the branch is ready, all these changes can be merged back into the
275 mainline of the project.
277 Ikiwiki powers its own bug tracking system. To see how wiki bug tracking
278 works in practice, visit the [[bugs]] or [[TODO]] pages.