From 868ce06b36377da65f79d888b1cb042adfb11161 Mon Sep 17 00:00:00 2001 From: joey Date: Sat, 14 Apr 2007 20:18:11 +0000 Subject: turn tips page into a feed --- .../integrated_issue_tracking_with_ikiwiki.mdwn | 275 +++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn (limited to 'doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn') diff --git a/doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn b/doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn new file mode 100644 index 000000000..a39b93656 --- /dev/null +++ b/doc/tips/integrated_issue_tracking_with_ikiwiki.mdwn @@ -0,0 +1,275 @@ +[[meta title="Integrated issue tracking with Ikiwiki"]] + +By Joey Hess, LinuxWorld.com + +[[template id=note text=""" +[First published](http://www.linuxworld.com/news/2007/040607-integrated-issue-tracking-ikiwiki.html) +on [LinuxWorld.com](http:://www.linuxworld.com/), a publication of Network +World Inc., 118 Turnpike Rd., Southboro, MA 01772. +"""]] + +Wikis are not just for encyclopedias and websites 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 where 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 edits in source code. + +Ikiwiki is a full-featured wiki that you can use +for a variety of purposes, from traditional wikis +to weblogs, podcasting, or even aggregating other +sites' RSS feeds into a Planet page. While people +are [[using|ikiwikiusers]] +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|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. + + _Really?_ + + 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 website. 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. + +Ikiwiki can also be tied into the [[post-commit]] hook of your revision +control system, so that whenever a developer commits a change to a wiki +page in revision control, the project's web site is automatically updated. +The [[ikiwiki_tutorial|setup]] explains in +detail how to set this up using the Subversion, Git, TLA, and Mercurial +revision control systems. + +The tutorial also explains how to configure ikiwiki so that users can edit +pages using a web interface, with their changes committed back into revision +control. After all, one of the benefits of keeping a project's docs in a wiki +is to make it easy for users to improve them, so that busy software developers +don't have to. And if the wiki is being used for issue tracking, this will +let users post and follow up on bug reports. + +## Using a wiki for issue tracking? + +You might be wondering exactly how a wiki can be used as an issue tracking +system. Three key parts of ikiwiki come together to create an issue tracker: +pages, tags, and inlining. + +Each issue is described on a separate page in the +wiki. There can also be an associated Discussion page, +as well as other related subpages that can be used +to hold files used to reproduce the bug, or patches, +or other related files. Since each issue is a page, +standard wiki links can be used to link related +issues, or link issues with other pages in the wiki. +Each issue has its own unique URL. Since ikiwiki +supports subdirectories, it's usual to keep all the +bugs in a `bugs/` subdirectory. You might prefer +to separate bugs and todo items, with todo items in +their own 'todo/' subdirectory. + +While directories are useful for broad hierarchical +grouping, tags are better for categorizing issues +as bugs, wishlist items, security issues, patches, +or whatever other categories are useful. Bugs can +be tagged "moreinfo", "done", "unreproducible", +etc, to document different stages of +their lifecycle. A developer can take ownership of a +bug by tagging it with something like "owner/Joey". + +To tag a wiki page, edit it and add text such as "\[[tag done]]". Note that +adding a wiki link to "\[[done]]" will have the same categorisation effect +as a tag, but the link will show up in the body of the page, which is a +nice effect if used in a sentence such as "This was \[[done]] in version +1.1.". Another way to close a bug is to move it out of the `bugs/` +subdirectory, though this would prevent it from showing up in a list of +closed bugs. + +Inlining is how ikiwiki pulls individual issue pages together into +something larger, be it a page listing recently opened bugs (with a form to +let a user easily post a new bug), or a page listing recently closed bugs, +or an index of all bugs, or all wishlist items, or RSS feeds for any of +these. A flexible syntax is used for specifying what kind of pages should +be inlined into a given page. A few examples: + +* A typical list of all open bugs, with their full text, and a form to post new + bugs. + + \[[inline pages="bugs/* and !link(done) and !*/Discussion" actions=yes postform=yes show=0]] + +* Index of the 30 most recently fixed bugs. + + \[[inline pages="bugs/* and link(done) and !*/Discussion" sort=mtime show=30 archive=yes]] + +* Index of the 10 most recently active bugs. + + \[[inline pages="bugs/* and !link(done) and !*/Discussion" sort=mtime show=10]] + +* Open security issues. + + \[[inline pages="bugs/* and link(security) and !link(done) and !*/Discussion"]] + +* Full text of bugs assigned to Joey. + + \[[inline pages="bugs/* and link(owner/Joey) and !link(done) and !*/Discussion" show=0]] + +It may seem strange to consider using a wiki for issue tracking when there +are several dedicated bug tracking systems, like Bugzilla, that handle all +aspects of it already. The weakest part of using ikiwiki for issue +tracking, and certainly the place where a dedicated bug tracker like +Bugzilla shines in comparison, is storing and querying structured data +about bugs. Ikiwiki has little structured data except for page filenames +and tags, so if you need lots of queryable data such as what versions a bug +affects and what version it was fixed in, ikiwiki may not be a good fit for +your issue tracking. + +On the other hand, by using a wiki for issue +tracking, there is one less system for users and +developers to learn, and all the flexibility of a +wiki to take advantage of. Ikiwiki even supports +[OpenID](http://openid.net/), so it's easy for users +to use it for filing bugs without going through an +annoying registration process. + +Developers who work offline, or at the other end of a +slow connection, might appreciate having a full copy +of the project bug tracking system, too. + + +## Benefits + +Realistically, there are plusses and minuses to letting users edit a +software project's documentation in a wiki. Like any wiki, to be +successful, some review is needed of the changes users make. In some cases +it will be easiest to limit the pages that users are allowed to edit. +Still, keeping the wiki open for user edits will probably turn up some +passionate users who prove very useful at filling in holes in the +documentation and cleaning up the site. + +Programmers are supposed to be bad at writing documentation, and putting a +project's docs into a wiki might not solve that. But it can make it a +little bit easier. Consider a programmer who's just coded up a new feature. +He can commit that to a development branch in revision control, and then go +update the docs on the web site to document it. But the feature isn't +available in a released version yet, so it's probably easier to skip +updating the website. Maybe once it's released, the web site will be +updated to mention the feature, but maybe (probably) not. + +Now consider what happens if instead the web site is a wiki that has its +source included in the project's revision control system. The programmer +codes up the feature, and can easily update the docs in the wiki to match. +When he commits his changes to a development branch, the docs are committed +too. Later, when that change is merged to the release branch, the doc +changes are also merged, and automatically go live on the web site. +Updating the documentation to reflect each change made and publishing it on +the website has become a standard part of the programmer's workflow. + +But this still requires programmers to write documentation, so maybe it +still won't work. Let's go back a step. Before the programmer wrote that +feature, he probably got some requests for it, and maybe he developed those +into a specification for how the feature should work. Since ikiwiki can be +used as an issue tracker, the requests were made using it, and were +collaboratively edited on the wiki, to develop the specification. Once the +feature is implemented, that issue can be closed. What better way to close +it than to move it out of the issue tracking system, and into the project's +documentation? In Subversion: + + svn mv wiki/bugs/new_feature.mdwn wiki/doc/ + +If the spec is written well enough to be useful for end user documentation, +the programmer doesn't have to write a lot of docs after all; that was done +when the feature was designed. By using ikiwiki for issue tracking, plus +editing the spec, plus documentation, plus the website, each of these steps +has built on the other and the programmer has had to do less busywork. + +A different example of how ikiwiki can tie +things together is how a security hole might be +handled. First it's discovered, and a bug filed about +it. When it's fixed, the commit that fixes the bug +can include a change to the bug's page, marking it +as done. Since it's a security hole, the project +needs to make an announcement right away so users +will know they need to upgrade. This announcement +can be added to the wiki's news feed, and committed +along with the fix, and the announcement can use a +regular wiki link to link to the bug that describes +the security hole in detail. If the security hole +also affects an older version of the software, the +fix, along with the wiki documentation for that fix, +can be merged into the branch for the older version. + +Another benefit of keeping the bug tracking system in revision control with +the wiki is that it allows for disconnected development. So there's no need +to be online to review the project's bug list, and there's no need to +remember to close fixed bugs once you're back online. + +For fans of distributed revision control, ikiwiki opens even more +possibilities. With a project's website and issue tracker kept in +distributed revision control with the project, these become distributed as +well, rather than centralized appendixes to the project. Developers can +pass around changesets that not only fix bugs, but mark them as done. If +large changes are being made in someone's branch, they can choose to put up +their own version of the website, use it to track bugs for that branch, and +when the branch is ready, all these changes can be merged back into the +mainline of the project. + +Ikiwiki powers its own bug tracking system. To see how wiki bug tracking +works in practice, visit the [[bugs]] or [[TODO]] pages. -- cgit v1.2.3