doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn

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