====== DokuWiki & Bugs/Issues ======

This page documents the close integration between this WikiEngine and some Bug Tracking / Issues Management systems. This documents assumes from now onward that Issues Management is more global (generic) than Bug Tracking, which seems to be a special case of the former. Use this document to discuss subjects about Issue Management and [[wiki:DokuWiki]]'s integration / interchange.\\ 

===== Bug Tracking for DokuWiki =====

DokuWiki now uses [[http://flyspray.rocks.cc|Flyspray]] for bugtracking (accessable at [[http://bugs.splitbrain.org|bugs.splitbrain.org]])
For tight integration between DokuWiki and Flyspray the Flyspray sourcecode was changed to use [[phpfn>md5]] instead of [[phpfn>crypt]] for encrypting passwords ((MD5 is available as builtin MySQL function which makes the integration with [[wiki:auth:mysql|auth_mysql]] much simpler and made the transfer of existing [[wiki:auth:plain|auth_plain]] DokuWiki accounts possible)). A patch to select the wanted password encryption in the config file was sent to the flyspray author and is included in the next release.

DokuWiki authenticates against the Flyspray database using [[wiki:auth:mysql|auth_mysql]] with the following options:

<code php>
$conf['authtype'] = 'mysql';

$conf['auth']['mysql']['server']   = 'localhost';
$conf['auth']['mysql']['user']     = 'flyspray';
$conf['auth']['mysql']['password'] = 'password';
$conf['auth']['mysql']['database'] = 'flyspray';
$conf['auth']['mysql']['passcheck']= "SELECT user_name
                                        FROM flyspray_users
                                       WHERE user_name='%u'
                                         AND user_pass=MD5('%p')
                                         AND account_enabled=1";
$conf['auth']['mysql']['userinfo'] = "SELECT real_name AS name, email_address AS mail
                                        FROM flyspray_users
                                       WHERE user_name='%u'";
$conf['auth']['mysql']['groups']   = "SELECT LOWER(a.group_name) as `group`
                                        FROM flyspray_groups a, flyspray_users b                                      
                                       WHERE b.group_in = a.group_id
                                         AND b.user_name='%u'";
</code>

To reference bugs an [[wiki:interwiki]] shortcut named ''bug'' was added which allows to link directly to a bugs detail page by its ID: %%[[bug>4]]%% -> [[bug>4]]

FlySpray seems to be a simple and easy to use Bug Tracking system. It's a good choice, specially since it seems the development team aims to integrate some sort of WikiParser into it, which will ease writing and editing descriptions. Still, some nice-to-have features are lacking:
  * RSS Feeder. This feature should allow people to use RSS Readers for being notified of new submissions or changes to existing entries in the system.  **Update:** This feature is in development, and will be in the next release.

**Authenticating against the Flyspray development version**\\
If you are running the [[http://flyspray.rocks.cc/development|development version of Flyspray]] (ie from the Subversion repository), you will need to use the following query for group authentication against the Flyspray database tables.
<code php>
$conf['auth']['mysql']['groups'] = "SELECT LOWER(g.group_name) AS `group`
                                    FROM flyspray_users u
                                    LEFT JOIN flyspray_users_in_groups uig ON u.user_id = uig.user_id
                                    LEFT JOIN flyspray_groups g ON uig.group_id = g.group_id
                                    WHERE u.user_name = '%u'
                                    AND uig.user_id = u.user_id
                                    AND g.belongs_to_project = '0'";
</code>
The above query retrieves a user's **Global** group.  If you want to allow wiki access only to members of a certain project, change the '0' in the last line to the project_id of your desired project.


===== Why flyspray? =====

Because I was asked I like to give you the reasons I chose [[http://flyspray.org/|Flyspray]] over [[http://mantis.sf.net|Mantis]] or [[http://dev.mysql.com/downloads/other/eventum/|Eventum]].

I had a look at all systems' sites mentioned below. Eventum sounded good but it didn't have a demo system for trying (or at least I didn't see it) and some features were not really needed by me. So I chose Mantis first. I installed it but somehow I didn't like the interface and configuration (very subjective). So I finally tried flyspray. It is very simple to install, easy to configure and comes close to DokuWiki's idea of KISS. I took me just 5 minutes to change it's password mechanism to MD5 - I really like it :-)

There are still features missing but I think it was a good choice non the less.

So as a conclusion: Why Flyspray? Just because I liked it ;-)

 --- //[[andi@splitbrain.org|Andreas Gohr]] 12.01.2005 18:24//

**Update** Now with flyspray in action for a month it's time to review my decision. I still like it but I encountered many glitches I don't like. I just want to list them here in no particular order:

  * lack of documentation - they have a Wiki but not publically editable, so the available documention is pretty scarce
  * Markdown for syntax formatting - this is somewhat counterintuitive and because there is no preview, most bugreports look like %%sh***%% ((I just had a short look into the current devel checkout and they seem to have dropped it again))
> This was discussed on the mailing-list and it probably will be removed from the next version because most people don't like it
  * the source is simple to understand but somewhat messy, lots of commented out legacy code is flying around

Well it's still a zero version so lets see what the future brings... Installing a bugtracker was definitive a good decision - it helps me to keep my work on DokuWiki organized.

 --- //[[andi@splitbrain.org|Andreas Gohr]] 2005-02-08 21:00//

I have also checked the 3 above mentioned bug tracking systems, and my order of preference is Eventum, Flyspray and Mantis. Mantis is the third for the same reason as yours (interface, usability). I've put Eventum in front of Flyspray for it's features (super fine grained ACL) and strong history (used by MySQL dev team). It's a pitty you have not installed it, since it is just a matter of uploading to a server and running a php file. The instalation process can take only 30 seconds and it does everything for you (including db setup).

Having said all this, I would like to ask if you have any plans to do somekind of integration between DokuWiki and Eventum. Just like Flyspray, the main thing missing is a integrated Wiki...

 --- //[[francisco@altermedia.com.br|Francisco Millarch]] 10.05.2005 12:44//

I am also looking for a Bugtracking-System that integrates with Dokuwiki. Are there any existing solutions or plans for an incorporation?

 --- //Andreas 17.08.2006 12:39//

**Update**

After evaluating both solutions a few more days, I decided to stick with Flyspray. I still think Eventum has some great features that should serve as basis for Flyspray improvement, but it's lack of support for language translations (you have to hack the templates) amoung other complexities, made me stick with Flayspray. The other issues that were preventing me from using Flyspray (notably ACL) is now fixed in the 0.98 development version.

--- //[[francisco@altermedia.com.br|Francisco Millarch]] 13.05.2005 12:58//


===== Issues Management =====
:?: What is Issue Management?\\
Issue Management systems are systems that handle the history of an issue. An issue can be a bug report, a feature request or a support request. For what I've seen, sometimes bugs and features are grouped together in a change request, and a support request is also known as a trouble ticket. These systems must manage the opening of a new issue, the reporting and history of its information, the changes in its status and its resolution. The system should be simple, pratical and easy to use, not to impose a tough learning curve on the users. 

> Does issue management include collaboration and version control (Perhaps CVS) or [[http://subversion.tigris.org/ |Subversion]] ?

>> IMHO, it doesn't. Or at least, collaboration and version control shouldn't be a requirement for an Issue Management system. But the system must integrate easily (link easily) with those systems, specially on software projects. -- 2004.10.02.


:?: What are the well known Issue Management systems?
  * [[http://www.bugzilla.org/ | BugZilla]] - Perl. People have reported that it's too complex to install, feature bloated, and other problems, but also seems to be the one everyone knows and uses.
  * [[http://scarab.tigris.org/ | Scarab]] - Java.
  * [[http://www.mantisbt.org/ | Mantis]] - PHP + MySQL + GPL. Seems to have a RSS Feeder, that indicates issue status changes or issue revisions. Notifies users by e-mail. Read the review [[http://www.linuxjournal.com/node/6859 | Mantis Bug Tracker]], from Glenn Stone in 2003.05.07.
  * [[http://dev.mysql.com/downloads/other/eventum/index.html | Eventum]] - PHP + MySQL + GPL. Seems to have a RSS Feeder, that indicates issue status changes or issue revisions. It also seems capable of handling issue reporting by e-mail messages. Notifies users by e-mail. It also requires PHP_GD for graphs, as well as jpgraph, PHP IMAP/POP3 must be enabled in PHP as well as PCRE and MySQL extensions (which usually are in latest PHP releases). Also seems to integrate with SCM systems, mainly CVS and has a command-line interface which may come in handy. See the [[http://dev.mysql.com/downloads/other/eventum/features.html | features]] page in the official site, for more information about it, or browse the [[http://dev.mysql.com/downloads/other/eventum/screenshots.html | screenshots]] to view some examples.
  * [[http://flyspray.org/ | FlySpray]] - PHP.
  * [[http://sourceforge.net/projects/kennwhite/ | CodeTrack]] - PHP.
  * [[http://www.edgewall.com/products/trac/ | Trac]] - Python + GPL. This system integrates easily with Subversion (version control) and has a collaboration Wiki engine, so it's a 3-in-1 system. The only requirement, besides Apache and Python, seems to be Subversion.
  * [[http://roundup.sf.net/ | Roundup]] - Python + Python License.  Bi-directional email.  Often chosen over Trac.
  * [[http://www.redmine.org | Redmine]] - MySQL, Ruby on Rails, GPL. Includes Iuuse tracking as well as Bug Tracking, RSS feeds, roles, Gantt charts, calendar, email notifications, forums, etc.

:?: What are the well known Trouble Ticket Management (HelpDesk) systems?
  * [[http://www.oneorzero.com | 1||0]] [[http://www.oneorzero.com/index.php?page=features | Features]] - PHP. This system doesn't have a RSS Feeder neither does it accept new ticket submissions by e-mail. It does have a FAQ section (although a Wiki is probably better at this) and is simple to use. Current version is 1.4.5.
  * [[http://osticket.com| osTicket]] [[http://osticket.com/index.php?option=articles&task=viewarticle&artid=1&Itemid=3 | Features]] - PHP and Perl. This system doesn't have a RSS Feeder neither does it have a FAQ section, but it does accept new ticket submission by e-mail, using a Perl script. Current version is 1.2.7 , since 2004.06.26, but the latest beta 1.3.0 is also available.
  * [[http://www.bestpractical/rt|Request Tracker]] - Perl. Has RSS, e-mail support, and some semblance of Wiki functionality with the RTFM add-on.
  * [[http://dcl.sourceforge.net|Double Choco Latte]] - now an official part of the GNUe umbrella project, and an official GNU project!  Very full-featured.

===== Other Links =====
  * [[http://linas.org/linux/pm.html | Call Center, Bug Tracking and Project Management Tools for Linux]]

===== Discussion =====

Besides not having a RSS Feeder that I can use to periodically receive notifications of changes I also can't use Wiki Syntax to describe the problem neither I can login. It seems that I have forget my password, since the username is already taken when I attempt to register again. I understand that having an organized system that categorizes bugs by type, severity, priority, and so on is a good thing and helpful to the development team. But I was so used to the bugs page that I see myself contributing less to the wishlist (feature requests), the bugs and help (support requests - tickets) in the new bug tracking system than I used to contribute when they were all WikiPages. -- straider (2005.01.12).

> There is a rss.php included in the flyspray sources I just have to see if it works already and if not what I have to do to make it work. So this issue will be addressed. About your login problems I just reset your password and sent it per mail to you. Anybody else who has problems with logging in please mail me!  --- //[[andi@splitbrain.org|Andreas Gohr]] 12.01.2005 13:04//

>> Login is working fine now. Thanks. Nevertheless, I do miss being able to add feature requests, support requests or reporting bugs using dokuwiki's sintax. Do you have any plans to integrate the wiki parser into flyspray?

> No this is not planned currently - i already have plenty of open buildingplaces :-/ When I find the time to make the parser a proper standalone class maybe this can be done... but for the forseeable future don't count on it.  --- //[[andi@splitbrain.org|Andreas Gohr]] 12.01.2005 13:43//

>> How can I help? I'm interested in having a standalone DokuWiki parser that can be integrated into other web applications. My goal is to replace existing textareas that allow html/php tags with DokuWiki GUI Editor and Wiki Parser. But this a topic for another discussion. On another topic, but on the bug tracking issue, I'd like to post a question since I'm curious about the possible replies: Why choose Flyspray over Mantis/Eventum/others?

On the same note, where should the "discussion" of some feature request/support request/bug report happen? Everything should be managed by the Bug Tracking system, or should a Task Entry point to a Discussion Page here on the WikiSite?

> I think adding comments in the BTS is the best way...  --- //[[andi@splitbrain.org|Andreas Gohr]] 12.01.2005 18:22//

>> I think its far more convenient to have discussions here rather than on the BTS. Take the npm.* newsgroups that mozilla uses for instance. People are encouraged to discuss their ideas with others before filing a bug request. Even casual users will find it easier to look through a [[wiki:discussion:discussion]] page instead of searching for the //correct// bug --- [[http://www.it.iitb.ac.in/~sameerds/wiki/doku.php | SameerDS]] 16 Jan 2005


Let me start by praising you on such a nice wiki, i had to find one at the last minute before a major project took off and the one i initaly chose i found couldnt meet the requirements 12 hours before the kick off.  I found Doku at the last min and managed to save some face, thanks. :-)\\
Now on to my question,  for the Flyspray integration you mention that we need to convert Flyspray to use md5 rather than crypt.  I have replaced all instances of crypt with md5 (and removed the salt parameter), and i am able to create a user in Flyspray and see that it puts a md5 value in the user table, but alas can not login to Flyspray nor doku with the password.

could you post the files that you modified in flyspray?\\
[[ryanpublic@stickystyle.net|Ryan P]]

> That's all I did. I replaced all calls to crypt with md5 as you described, but remember: md5 produces 32 characters - crypt is shorter, so you have to adjust the password field in the database, too.  --- //[[andi@splitbrain.org|Andreas Gohr]] 22.01.2005 09:30//
>>Ahhhh, of course. Thanks it works now :-)
>>>Perhaps you can release the patches upstream? :D
>>>> I would really appreciate a more detail explanation of what needs modifying to change from crypt to md5, which files? is it simply a string substitution? Thanks

I'm also having a had time implementing this integration. Could someone provide a better step-by-step guide? Which files and lines to change, etc...

[[francisco@altermedia.com.br|Francisco Millarch]]

I'm more than happy to have Wiki syntax support in Flyspray.  Why don't we already?  Probably because no one has ever asked us for it (if I remember correctly).


[[DJMurtz@hotmail.com|Jean]]

I too have problems integrating flyspray with dokuwiki. I changed the line "$conf['authtype']" from "plain" to "mysql" and added all the other "$conf['auth']['mysql'] lines below that line. Changed "$conf['passcrypt']" to "md5" and also changed the encryption used by flyspray to md5 by editing the flyspray.conf.php. Finally I changed the database to accept 32char strings in the password field and updated to password of the admin to a md5-encrypted password. I am now able to login in flyspray, but not in dokuwiki...

[[http://flyspray.rocks.cc/|Tony Collins]]

Can I still use ACL if I integrate Flyspray with DokuWiki? I'm afraid to break anything. How do I disallow certain groups from viewing certain namespaces, now that I am using the MySQL authentication?

For Tony: My Flyspray & DokuWiki have been successfully integrated. I followed the instructions [[http://discerning.com/hacks/flyspray/|stated here]]

[[http://chette.com|Chette Soriano]]