It's difficult to determine whether Redmine is rather a project management tool or an issue tracker. Issue tracking is not possible without a project (while some project management is still possible without issues). Even so, we spend most of our time working with Redmine as an issue tracker. This appears to be a fundamental component of Redmine that nevertheless depends on its other components. So, to use Redmine effectively, you have to learn it. For these reasons, we will start reviewing Redmine's functionality from its issue tracking capabilities.
In other words, the Issue tracking module is too deeply tied to other Redmine modules to be reviewed separately. But the opposite is also true—other modules use issues too extensively to skip issue tracking and start from reviewing other components. So, in this chapter, we will try to concentrate on issue tracking while also mentioning other modules if and where they are applicable. But don't worry if you are not familiar with mentioned modules yet! I will let you know where you'll be able to check them quickly.
In this chapter, we will cover the following topics:
- Creating an issue
- The issue page
- The issue list
- Updating an issue
- Issue reports
- Importing issues
- Keeping track of changes
- Issue-related settings
In order to be able to create an issue, you need to have a project already. So, create one if you haven't done this yet (use the New project link that can be found under the Projects menu item). You can also jump to the Creating a project section in Chapter 5, Managing Projects, where project creation is described, and then come back here.
If you already have a project, or after you have created it, navigate to the New issue tab in the Projects menu. You will see the following form:
This is the form that Redmine users use to create issues. Fields that are marked with the red asterisk 
are mandatory.
Note
Issues can be also created via email if you have configured the email retrieval (as described in the Email retrieval subsection of Chapter 3, Configuring Redmine), or through third-party tools if you have enabled the REST API.
Let's discuss each element of this form:
- In Redmine, the Tracker name is used to describe the type of the issue. Thus, the appropriate element in JIRA (a popular commercial alternative to Redmine) is named literally Issue type. By default, Redmine comes with the following trackers:
- Bug
- Feature
- Support
You can delete, modify, or add trackers using the Trackers page of the Administration menu, which will be reviewed in Chapter 7, Access Control and Workflow. For my demo project, I have added a new tracker called Chapter, which you can see selected in the previous screenshot.
- The Private checkbox can be used to make the issue visible only to you and other members of groups that you are a member of. If the project is private as well, such users are also required to be members of the project.
- The Subject field should briefly describe the issue (like, for example, an email subject describes the message). In most cases, the tracker and the subject of the issue (in addition to the unique numerical identifier) are the only fields that users see on other Redmine pages that mention the issue. For this reason, the content of this field should be chosen with care.
-
I believe that the Description field does not need an explanation. But it's worth mentioning that for this field you can use rich text formatting. To get an idea about its capabilities, you can click on the last button
of the upper toolbar. We will review the appropriate Wiki syntax in Chapter 6, Text Formatting.
- The Status field indicates the status of the issue, such as whether it is active, whether anyone is working on it, whether it is already resolved, and so on. In the previous screenshot, the status was set to New as that was a new issue, and this status was selected by default (I just did not change it). The available issue statuses, their order and the default status can be configured on the Issue statuses and Trackers pages of the Administration menu.
- The Priority field reflects how urgent or critical the issue is. The values for this field and their order can be managed on the Enumeration page of the Administration menu. There, you can also select the default value (which is Normal by default).
- The Assignee field holds the name of the user who will be responsible for handling the issue. Only members of the project or the original issue author can be selected here. That is, if you want to assign an issue to someone, you must first ensure that that person is a member of the project (new members can be added under the Members tab of the project's Settings page).
- The Parent task field can hold the numerical identifier of another issue to which the new issue will be added as a subtask. To help you identify the right issue, when you type a value Redmine shows the autocomplete box with a list of matching issues and their subjects.
- The Start date and Due date fields can be used to set the period during which the issue has to be resolved. Nonetheless, they don't have to be specified together. These attributes, if both are set, are used to display the issue on the project's Gantt chart. Also, each of these attributes is used to display the issue on the calendar. By default Redmine sets the Start date field to the current date, what can be disabled under the Issue tracking tab of the Settings page in the Administration menu.
- The Estimated time field can be used to specify how many hours it should take to resolve the issue. This attribute can be especially useful if you are using the, Time tracking project module (which is described in Chapter 8, Time Tracking), as it allows you to control the time spent on the issue.
- The % Done field, also known as the done ratio, indicates how much percentage of the issue has been resolved. Thus, it should ideally be 0% by the start date, and by the due date, it should be 100%. The value specified here is shown on the Gantt chart and is used for the project roadmap to show the overall progress for the corresponding version.
- Redmine allows you to add any number of attachments to an issue. Each attachment can have a description (the special textbox for the description appears as soon as you upload a file to the issue form). The size of each file is limited by the Maximum attachment size setting, which can be found under the General tab of the Settings page in the Administration menu.
- Each issue can be watched. By watching the issue, you will:
- Be able to see a list of issues that you watch on My page (if you have enabled the Watched issues block there; this page is going to be reviewed in Chapter 9, Personalization). In this way, you can have a kind of a list of favorite issues.
- Be notified via email about any changes made to the issue (if email notifications have been enabled and properly configured; refer to Chapter 3, Configuring Redmine, to learn how to do this).
- The new issue form, which you can see in the previous screenshot, includes checkboxes only for members of the project. To add non-members to the Watchers list, you need to click on the Search for watchers to add link.
- When you have finished editing the issue, you can click on the Create button to submit it and open its page. Alternatively, if you need to add another issue, you can click on the Create and continue button to save the current issue and get the new issue form again.
- The Preview link can be used to preview the issue description, in particular to check how the Wiki markup will be rendered.
Some of the discussed form elements, which are also known as standard fields, can be disabled for particular trackers on the Trackers page of the Administration menu. Most of them can also be made required or read-only per issue status, member role, and tracker on the Workflow page of the same menu. Both of these pages will be reviewed in Chapter 7, Access Control and Workflow.
Additionally, Redmine supports custom fields for issues, which can add their own elements to the issue form as well. Custom fields are going to be reviewed in Chapter 11, Customizing Redmine.
Even so, these are not all the elements that this form can include. There can be more elements added when you configure the project. The project configuration is discussed in detail in the very next chapter. Now let's talk about only those things that add new elements to the new issue form.
In many cases, having just the tracker (the issue type) is not enough to describe an issue. To see what I mean, let's take the Feature tracker. Is an issue of this tracker for a UI feature? Is it for a new functionality of the project? Is it, maybe, for an API feature? As you can see, for some complex projects, you may need an additional attribute to make the issue more concrete. And Redmine does provide such an issue attribute. But why did not we see it? Because we need to add at least one value for this field to make it appear on the issue form.
Such values can be added in the Issue categories tab, which can be found in the project's settings (the Settings tab of the project menu). Here is what this tab looks like:
As you can see, there are no issue categories here for now. To add an issue category, you need to click on the New category link. Then you'll see the following form:
The Assignee field of this form can be set to a user to whom issues of this category should be automatically assigned (unless of course the assignee was specified explicitly). Thus, if you have different employees responsible for different parts of the project, you can create categories named after those parts and specify the corresponding employees here as assignees for those categories. In this way, a reporter will only need to select a part of the project and the issue will automatically get assigned to the corresponding employee.
But wait! How will reporters select the issue category? If you check out the new issue form after you have added an issue category, you will see an additional field there, as shown in this screenshot:
The 
icon at the right-hand side of the field appears only for users who have the Manage issue categories permission. Such users may add issue categories right from the issue form.
Normally, a project has multiple planned versions. If so, in which of them is a particular issue planned to be resolved? This question draws attention to the need to be able to assign an issue to a project version. However, the issue form that was shown earlier did not include any field for this. Well, the project that I used did not have any version either.
As soon as you add a version to the project using the Versions tab, which can be found on the project's Settings page, the new field appears on the form, as shown in the following screenshot:
The new Target version field should be set to the name of the version in which the issue should be resolved. If it's set, the issue will also be listed on the project roadmap and in the version's change log (both will be reviewed in Chapter 5, Managing Projects).
Similar to the one near the Category field, the icon allows you to add a version directly from the issue form. Of course, to be able to do this, you must have the Manage versions permission. You will learn more details about version management in the next chapter.