turn tips page into a feed

1 files changed, 275 insertions, 0 deletions

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.