project_management.sgml

<chapter id="admin.project">
    <title>Project Management</title>

    <para>This section covers the project management features of MantisBT.  This includes features like change log, roadmap, time tracking, reporting and others.</para>

    <section id="admin.project.changelog">
        <title>Change Log</title>

        <para>MantisBT doesn't just track the status of issues, it also relates issues to versions.  Each project can have several versions, which are marked with attributes like released and obsolete.  Users typically report issues against released issues and developers typically fix issues in not released versions.  With every new release comes question like: what's new?  what has been fixed?  Customers wonder if the new release is of interest to them and whether they should take an upgrade.  Well, the change log is specifically tailored to answer these kind of questions.</para>

        <para>In order for an issue to show up in the change log, it has to satisfy certain criteria.  The criteria is that the issue has to be resolved with a 'fixed' resolution and has to have the 'fixed_in_version' field set.  Users sometimes wonder why resolved or closed issues don't show up in the change log, and the answer is that the 'fixed_in_version' field is not set.  Without the 'fixed_in_version', it is not possible for MantisBT to include the issues in the appropriate section of the changelog.  Note that it is possible to set the 'fixed_in_version' for multiple issues using the 'Update Fixed in Version' group action on the View Issues page (just below the issues list).  This option is only available when the selected project is not 'All Projects'.  Once a version is marked as obsolete, it is now longer included in the change log.</para>

        <para>MantisBT also provides the ability to customize the criteria used for an issue to be included in the change log.  For example, for installations that use a custom set of resolutions, it is possible to select multiple resolutions as valid candidates for the change log.  This can be done using custom functions (see custom functions documentation for more details).  The custom function below overrides the MantisBT default behavior to include issues with both FIXED and IMPLEMENTED (a custom resolution) resolutions in the change log.

<programlisting>
# --------------------
# Checks the provided bug and determines whether it should be included in the changelog
# or not.
# returns true: to include, false: to exclude.
function custom_function_override_changelog_include_issue( $p_issue_id ) {
    $t_issue = bug_get( $p_issue_id );

    return ( ( $t_issue->resolution == FIXED || $t_issue->resolution == IMPLEMENTED ) &&
        ( $t_issue->status >= config_get( 'bug_resolved_status_threshold' ) ) );
}
</programlisting>
        </para>

        <para>MantisBT also provides the ability to customize the details to include from the issue and in what format.  This can be done using the following custom function.

<programlisting>
# --------------------
# Prints one entry in the changelog.
function custom_function_override_changelog_print_issue( $p_issue_id, $p_issue_level = 0 ) {
    $t_bug = bug_get( $p_issue_id );

    if ( $t_bug->category_id ) {
        $t_category_name = category_get_name( $t_bug->category_id );
    } else {
        $t_category_name = '';
    }

    $t_category = is_blank( $t_category_name ) ? '' : '&lt;b&gt;[' . $t_category_name . ']&lt;/b&gt; ';
    echo str_pad( '', $p_issue_level * 6, '&nbsp;' ), '- ', string_get_bug_view_link( $p_issue_id ), ': ', $t_category, string_display_line_links( $t_bug->summary );

    if ( $t_bug->handler_id != 0 ) {
        echo ' (', prepare_user_name( $t_bug->handler_id ), ')';
    }

    echo ' - ', get_enum_element( 'status', $t_bug->status ), '.&lt;br /&gt;';
}
</programlisting>
        </para>

        <para>By combining both customization features, it is also possible to do more advanced customization scenarios.  For example, users can add a 'ChangelogSummary' custom field and include all issues that have such field in the change log.  Through customizing what information being included for a qualifying issue, users can also include the 'ChangelogSummary' text rather than the native summary field.</para>

        <para>In some cases, users know that they fixed an issue and that the fix will be included in the next release, however, they don't know yet the name of the release.  In such case, the recommended approach is to always have a version defined that corresponds to the next release, which is typicalled called 'Next Release'.  Once the release is cut and has a concrete name, then 'Next Release' can be renamed to the appropriate name and a new 'Next Release' can then be created.  For teams that manage releases from multiple branches for the same project, then more than one next release can be possible.  For example, 'Next Dev Release' and 'Next Stable Release'.</para>

        <para>Another common requirement is to be able to link to the change log of a specific project from the project's main website.  There is a variety of ways to do that:
            <itemizedlist>
                <listitem>
	                <para>To link to the changelog of version "ver1" of project "myproject":
						<programlisting>
						http://www.example.com/mantisbt/changelog_page.php?project=myproject&amp;version=ver1
						</programlisting>
	                </para>
                </listitem>
                <listitem>
                	<para>To link to the changelog of all non-obsolete versions of project 'myproject':
						<programlisting>
						http://www.example.com/mantisbt/changelog_page.php?project=myproject
						</programlisting>
                	</para>
                </listitem>
                <listitem>
                	<para>To link to the changelog of project with id 1.  The project id can be figured out by going to the management page for the project and getting the value of project_id field form the URL.  
						<programlisting>
						http://www.example.com/mantisbt/changelog_page.php?project_id=1
						</programlisting>
                	</para>
                </listitem>
                <listitem>
                	<para>To link to the changelog of version with id 1.  The version id is unique accross all projects and hence in this case it is not necessary to include the project id/name.  The version id can be figured out by going to the manage project page and editing the required version.  The version_id will be included in the URL.
						<programlisting>
						http://www.example.com/mantisbt/changelog_page.php?version_id=1
						</programlisting>
                	</para>
                </listitem>
            </itemizedlist>
        </para>

        <para>Another approach is to go to the project page and from there users can get to multiple other locations relating to the project include the change log.  This can be done by a URL like the following:
<programlisting>
http://www.example.com/mantisbt/project_page.php?project_id=1
</programlisting>
        </para>

        <para>It is possible to customize the access level required for viewing the change log page.  This can be done using the $g_view_changelog_threshold configuration option.</para>
    </section>

    <section id="admin.project.roadmap">
        <title>Roadmap</title>

        <para>
            One of the very important scenarios in project management is where the project managers (or team leads) triage the issues to set their priorities, target version, and possibly assign the issues to specific developers or take other actions on the issue.  By setting the target version of an issue to a version that is not yet released, the issue shows up on the project roadmap, providing user with information about when to expect the issues to be resolved.  The roadmap page has a section for each release showing information like planned issues, issues done and percentage of issues completed.  Issues that are fixed in a specific version, but didn't have the target_version field set, will not show up in the roadmap.  This allows the ability to control the issues that are significant enough to show in the roadmap, while all resolved fields can be found in the change log.  Note that it is possible to set the 'target_version' for multiple issues using the 'Update Target Version' group action that is available through the View Issues page (below the issues list).  This option is only available when the current project is not 'All Projects'.  Although it is not a typical scenario, it is worth mentioning that once a version is marked as obsolete, it is not included in the roadmap.
        </para>

        <para>
            Note that the roadmap only includes future versions, once a version is marked as released, it no longer is included in the roadmap.  For information about such releases, the change log feature should be used.  For an issue to be shown on the roadmap, it has to have the target version set.  It does not matter whether the feature is resolved or not.  Resolved features will be decorated with a strikethrough and will be counted as done.
        </para>

        <para>
            MantisBT provides the ability to customize the criteria for issues to show up on the roadmap.  The default criteria is that the issue has to belong to a version that is not yet released and that the issues is not a duplicate.  However, such criteria can be customized by using custom functions as below.

<programlisting>
# --------------------
# Checks the provided bug and determines whether it should be included in the roadmap or not.
# returns true: to include, false: to exclude.
function custom_function_override_roadmap_include_issue( $p_issue_id ) {
    return ( true );
}
</programlisting>
        </para>
        <para>
            It is also possible to customize the details included about an issues and the presentation of such details.  This can be done through the following custom function:

<programlisting>
# --------------------
# Prints one entry in the roadmap.
function custom_function_override_roadmap_print_issue( $p_issue_id, $p_issue_level = 0 ) {
    $t_bug = bug_get( $p_issue_id );

    if ( bug_is_resolved( $p_issue_id ) ) {
        $t_strike_start = '&lt;strike&gt;';
        $t_strike_end = '&lt;/strike&gt;';
    } else {
        $t_strike_start = $t_strike_end = '';
    }

    if ( $t_bug->category_id ) {
        $t_category_name = category_get_name( $t_bug->category_id );
    } else {
        $t_category_name = '';
    }

    $t_category = is_blank( $t_category_name ) ? '' : '&lt;b&gt;[' . $t_category_name . ']&lt;/b&gt; ';

    echo str_pad( '', $p_issue_level * 6, '&nbsp;' ), '- ', $t_strike_start, string_get_bug_view_link( $p_issue_id ), ': ', $t_category, string_display_line_links( $t_bug->summary );

    if ( $t_bug->handler_id != 0 ) {
        echo ' (', prepare_user_name( $t_bug->handler_id ), ')';
    }

    echo ' - ', get_enum_element( 'status', $t_bug->status ), $t_strike_end, '.&lt;br /&gt;';
}
</programlisting>
        </para>

        <para>
            Some teams manage different branches for each of their projects (e.g. development and maintenance branches).  As part of triaging the issue, they may decide that an issue should be targetted to multiple branches.  Hence, frequently the request comes up to be able to target a single issue to multiple releases.  The current MantisBT approach is that an issues represents an implementation or a fix for an issue on a specific branch.  Since sometimes applying and verifying a fix to the two branches does not happen at the same time and in some cases the approach for fixing an issue is different based on the branch.  Hence, the way to manage such scenario is to have the main issue for the initial fix and have related issues which capture the work relating to applying the fix to other branches.  The issues for porting the fix can contain any discussions relating to progress, reflect the appropriate status and can go through the standard workflow process independent of the original issues.
        </para>

        <para>Another common requirement is to be able to link to the roadmap of a specific project from the project's main website.  There is a variety of ways to do that:
            <itemizedlist>
                <listitem>
	                <para>To link to the roadmap of version "ver1" of project "myproject":
						<programlisting>
						http://www.example.com/mantisbt/roadmap_page.php?project=myproject&amp;version=ver1
						</programlisting>
	                </para>
                </listitem>
                <listitem>
                	<para>To link to the roadmap of all non-obsolete versions of project 'myproject':
						<programlisting>
						http://www.example.com/mantisbt/roadmap_page.php?project=myproject
						</programlisting>
                	</para>
                </listitem>
                <listitem>
                	<para>To link to the roadmap of project with id 1.  The project id can be figured out by going to the management page for the project and getting the value of project_id field form the URL.  
						<programlisting>
						http://www.example.com/mantisbt/roadmap_page.php?project_id=1
						</programlisting>
                	</para>
                </listitem>
                <listitem>
                	<para>To link to the roadmap of version with id 1.  The version id is unique accross all projects and hence in this case it is not necessary to include the project id/name.  The version id can be figured out by going to the manage project page and editing the required version.  The version_id will be included in the URL.
						<programlisting>
						http://www.example.com/mantisbt/roadmap_page.php?version_id=1
						</programlisting>
                	</para>
                </listitem>
            </itemizedlist>
        </para>

        <para>Another approach is to go to the project page and from there users can get to multiple other locations relating to the project include the roadmap.  This can be done by a URL like the following:
<programlisting>
http://www.example.com/mantisbt/project_page.php?project_id=1
</programlisting>
        </para>

        <para>
            The access level required to view and modify the roadmap can be configured through $g_roadmap_view_threshold  and $g_roadmap_update_threshold respectively.  Modifying the roadmap is the ability to set the target versions for issues.  Users who have such access can set the target versions while reporting new issues or by updating existing issues.
        </para>
    </section>

    <section id="admin.project.timetracking">
        <title>Time Tracking</title>

        <para>
					This is currently a work in progress. To follow the work have a look on the wiki page <ulink url="http://www.mantisbt.org/wiki/doku.php/mantisbt:issue:4428">Time Tracking (Issue 4428)</ulink>
				</para>

        <para>
					To activate the Time Tracking feature you have to set the configuration option "time_tracking_enabled" to ON. To activating the Time Tracking you can :
					<itemizedlist>
						<listitem><para>

							Static solution : change the variable '$g_time_tracking_enabled' in the configuration file 'config_defaults_inc.php', this will change the configuration for all the MantisBT instance ; 
						</para></listitem>
						<listitem><para>
							Dynamic and "project by project" solution : Use the administration page "Manage Configuration" and set the variable 'time_tracking_enabled' to '1' for which user and which project of you choice.
						</para></listitem>
					</itemizedlist>
				</para>
		
				<para>
					All Time Tracking configuration options are described in the configuration section off this guide.
				</para>
				
    </section>

    <section id="admin.project.graphs">
        <title>Graphs</title>

        <para>Assigned to me: TODO</para>
        <para>Release Delta: TODO</para>
        <para>Category: TODO</para>
        <para>Severity: TODO</para>
        <para>Severity / Status: TODO</para>
        <para>Daily Delta: TODO</para>
        <para>Reported by Me: TODO</para>
    </section>

    <section id="admin.project.summary">
        <title>Summary Page</title>

        <para>By Status: TODO</para>
        <para>By Severity: TODO</para>
        <para>By Category: TODO</para>
        <para>Time Stats for Resolved Issues (days): TODO</para>
        <para>Developer Status: TODO</para>
        <para>Reporter by Resolution: TODO</para>
        <para>Developer by Resolution: TODO</para>
        <para>By Date: TODO</para>
        <para>Most Active: TODO</para>
        <para>Longest Open: TODO</para>
        <para>By Resolution: TODO</para>
        <para>By Priority: TODO</para>
        <para>Reporter Status: TODO</para>
        <para>Reporter Effectiveness: TODO</para>
    </section>
</chapter>