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