This pages outlines the approach to be taken in order for Mantis to support integration with a Wiki.

Mantis covers very well the area of bugtracker, however, when developers are implementing features that require some sort of upfront brain storming, documentation, and design, the notes approach may become a bit overwhelming. I find that notes are very good for people to provide their thoughts. However, eventually the developer needs to put these thoughts together into one artifact that reflects what exactly will be implemented. This then becomes the basis for documentation, testing, etc.

For agile environments the use of Wiki to manage such documentation is a good option. This can include a description of the feature, some implementation notes, and even some testing notes.

Mantis users must not need to login into the Wiki. The wiki must automatically recognise the logged in Mantis user.

What a user can do must depend on their Mantis access level. For example, viewers and reporters may only be able to view the wiki, updaters may be able to edit it, developers/managers/administrators to create pages. The authorisation must also take into consideration the project and whether the issue is private/public.

The integration must be implemented in a way where it is possible to integrate multiple wiki engines with Mantis. The choice may be based on the preference of the company that is using Mantis. However, the Mantis development team will probably only support one integration. At the moment this is the integration with DokuWiki.

• The issue view pages must have a link that points to the Wiki page that corresponds to the current issue. If the page doesn't exist and the user has the appropriate access level, then a page can be created.
• It should be possible to add a Wiki column that has an icon that links directly to the Wiki page. This is similar to the pen icon that links directly to the update page.
• string_display_links() should also detect wiki links and hyper link them.
• Configuration items must be added to allow turning on/off Wiki integration, specify the engine, root of the wiki web, root of the wiki file path, etc.
• wiki_api.php, an API that allows Mantis code-base to deal with the Wiki generically. When calling this API, the calling code must not need to know the wiki engine being used.
• wiki_dokuwiki_api.php, there will be one of these per support Wiki engine (replace “dokuwiki” with the engine name). Such drivers will provide the necessary engine specific implementations that are used by wiki_api.php.
• Each project should be associated with a wiki page. This page acts as the root for project documentation. Links to this page should be added in locations like proj_doc_page.php. It may even be useful to have “Wiki” as an option in the menu. Mantis administrators can decide whether to include in the menu the Docs, Wiki, none, or both.
• Each version should be associated with a wiki page. This page will typically be used for release notes. It can also be used for planning the scope of a release.
• Each user (or at least developer and above) should be associated with a wiki page. This can be the home page for this developer.

The wiki engine will be changed as follows:

• Use Mantis authentication.
• Use Mantis authorisation (access control).
• Support for adding a header and footer that integrates the Wiki into Mantis interface and potentially into the customer's website.
• Ability to link to a Mantis issue (similar to #123 that is used within Mantis).
• Support for Mantis specific fields, e.g. id, summary, reporter, developer, etc. Such fields will be replaced at rendering time with actual values supplied by Mantis.
• Mantis Menu
• The issue wiki page must have a link back to the view page of the issue.

Ideally the Wiki data should be stored in the same database as Mantis. If for some reason the Wiki engine doesn't support all the DBMSes supported by Mantis, then file based storage should be used.

• Mantis should provide the flexibility to link with a Wiki that is installed in any location on the same server or network. The requirement is for Mantis to be able to include script files from the Wiki engine it is integrating with. This will typically be done in the wiki engine specific API.
• In the case where the Wiki is used only by Mantis, then it would be placed under the Mantis folder (e.g. mantis/dokuwiki).
• In the case where the Wiki will be used outside the scope of Mantis, then it would be placed in another location. This can be a sibling directory to Mantis root directory (e.g. htdocs/mantis and htdocs/dokuwiki).

Notifications related to Wiki page changes will be handled by the Wiki engine. Wiki engines typically provide an RSS or email support for providing users with such modifications. In the case where the Wiki engine supports email notifcations, the integration should allow making user email addresses stored in Mantis available to the Wiki engine.

There are several approaches for how the Wiki is to be structured. Each approach has its advantages and disadvantages.

• Mantis:Project - In this scenario there is a top level namespace (with configurable name) that includes all Mantis related wiki pages. Within this namespace there is a namespace per project, the project name space will have project documentation as well as issue related wiki pages.
  • Advantage: Nice structure, no need to use namespaces for internal links within the same project.
  • Advantage: It will be easier to backup all pages relating to a project, these may be imported somewhere else. For example, in the case of Docuwiki file storage, a namespace is a folder.
  • Disadvantage: If an issue is moved from one project to another, some manual or automated handling will have to be done.
• Mantis - A single namespace that includes a page per issue and a page per project. These will be the entry points.
  • Disadvantage: not nicely structured.

There should be some support for Wiki page templates. Each project may have a set of templates associated with it. The user may then choose which template to use when creating a new page. It is also possible to auto-select the template based on a custom function. The default implementation can be driven by some database configuration, however, custom implementations will be able to provide more complex criteria for the selection of the template to be used. The scope of this feature will be refine once the availability fo such feature in Wikis is researched. The idea is to avoid having to modify Wiki code, the solution should depend on out-of-the-box functionality or functionality that is implemented as a plug-in.

• Moving issues between projects.
• Deleting an issue.
• Cloning an issue.
• Deleting a project.
• Private projects/issues.
• Changing a project name.

• Mantis will be distributed with the code necessary to integrate with the Wiki, but not with the code of the actual Wiki.
• Enough documentation will be able to indicate the supported Wikis and whatever work necessary to get the integration working.
• In the future, a default Wiki may be included as part of Mantis distribution.

• DokuWiki
• Mediawiki, of course as well

• WikiMatrix - A website that compares Wiki engines.
• PEAR::Text_Wiki - A PEAR package for converting Wiki text to XHTML. It supports syntax for multiple Wiki engines.