doc/tips/issue_tracking.mdwn

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