path: root/doc/docbook/en/redmine-userdoc-en.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book>
  <title>Documentation</title>

  <chapter>
    <title>Administration</title>

    <section>
      <title>Projects</title>

      <para>These screens allow you to manage projects.</para>
    </section>

    <section>
      <title>Users</title>

      <para>These screens allow you to manage the application users.</para>

      <section>
        <title>Users’ List</title>

        <para></para>

        <screenshot>
          <screeninfo>Users’ List</screeninfo>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/users_list.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para>Accounts status:</para>

        <itemizedlist>
          <listitem>
            <para>This icon <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/locked.png" />
                </imageobject>
              </inlinemediaobject> means that the account is locked. A user
            having a locked account cannot log in and access the
            application.</para>
          </listitem>

          <listitem>
            <para>This icon <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/user_new.png" />
                </imageobject>
              </inlinemediaobject> means that the user hasn't yet actived his
            account.</para>
          </listitem>
        </itemizedlist>

        <para>The Lock/Unlock buttons allow you to lock/unlock the user
        accounts.</para>

        <para></para>
      </section>

      <section>
        <title>User Creation or Modification</title>

        <para>In modification mode, please leave the Password field blank in
        order to keep the user’s password unchanged.</para>

        <para>A user designated as administrator has unrestricted access to
        the application and to all projects.</para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">Administrator</guilabel> :
            designate the user as the administrator of the application.</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">E-mail notifications</guilabel> :
            activate or de-activate automatic e-mail notifications for this
            user</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Locked</guilabel> : de-activates
            the user’s account</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>
    </section>

    <section>
      <title>Roles and Permissions</title>

      <para>Roles organize the permissions of various members of a project.
      Each member of a project has a one Role in a project. A user can have
      different roles in different projects.</para>

      <para>On the new or edit Role screen, check off the actions authorized
      for the Role.</para>
    </section>

    <section>
      <title>Trackers</title>

      <para>Trackers allow the sorting of Issues and can define specific
      workflows.</para>
    </section>

    <section>
      <title>Custom fields</title>

      <para>Custom fields allow you to add additional information in Projects,
      Issues or Users. A custom field can be of one the following
      types:</para>

      <itemizedlist>
        <listitem>
          <para><guilabel moreinfo="none">Integer</guilabel> : positive or
          negative number</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">String</guilabel> : a string of
          characters - one single line of input.</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Text</guilabel> : a string of
          characters with multiple lines of input. Differs from String Format
          by providing multiple lines of input instead of a single
          line.</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Date</guilabel> : date</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Boolean</guilabel> : true or false
          (check if necessary)</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">List</guilabel> : value to select
          from a predefined list (aka: scroll list or select box)</para>
        </listitem>
      </itemizedlist>

      <para>Validation elements can be defined:</para>

      <itemizedlist>
        <listitem>
          <para><guilabel moreinfo="none">Required</guilabel> : A required
          field must have input in the forms</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">For all the projects</guilabel> :
          field automatically associated to all of the projects</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Min - max length</guilabel> :
          minimum and maximum length for the input fields (0 means that there
          is no restriction)</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Regular Expression</guilabel> :
          regular expressions may provide validation of the input value</para>

          <para>Examples:</para>

          <para><code>^\[A-Z]{4}\d+$</code> : 4 capital letters followed by
          one or several digits</para>

          <para><code>^[^0-9]*$</code> : characters only - no digits</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Possible values</guilabel> :
          possible values for the fields of "List" type. Values are separated
          by the character |</para>
        </listitem>
      </itemizedlist>

      <para></para>

      <section>
        <title>Fields for Projects</title>

        <para></para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">Required</guilabel> : required
            field</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>

      <section>
        <title>Fields for Issues</title>

        <para></para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">For all projects</guilabel> :
            field automatically associated to all project Issues</para>

            <para>If this option is not activated, each project could choose
            whether or not to use the field for its Issues (please see the
            project configuration).</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>

      <section>
        <title>Field for Users</title>

        <para></para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">Required</guilabel> : required
            field</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>
    </section>

    <section>
      <title>Issue status</title>

      <para>These screens allow you to define the different possible Issue
      statuses.</para>

      <itemizedlist>
        <listitem>
          <para><guilabel moreinfo="none">Closed</guilabel> : indicates Issue
          is considered as closed</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Default</guilabel> : status applied
          by default to new Issue requests (only one status can be Default
          status)</para>
        </listitem>

        <listitem>
          <para><guilabel moreinfo="none">Color</guilabel> : HTML color code
          (6 characters) representing the displayed status</para>
        </listitem>
      </itemizedlist>

      <para></para>
    </section>

    <section>
      <title>Workflow</title>

      <para>The workflow allows to define changes the various project members
      are allowed to make on the Issues, according to their type.</para>

      <para>Select the role and the tracker for which you want to modify the
      workflow, then click Edit. The screen allows you then to modify the
      authorized change, for the chosen role and tracker. The Current Status
      options indicate the initial request status. The "New Statuses allowed"
      columns stand for the authorized status to apply.</para>

      <para><remark>Note: In order for a particular Role to change an Issue
      status, the authorization must be given to it explicitly, regardless of
      the workflow configuration.</remark></para>

      <para></para>

      <screenshot>
        <screeninfo>Example of a workflow configuration</screeninfo>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/workflow.png" />
          </imageobject>
        </mediaobject>
      </screenshot>

      <para>In the above example, Bug type Issue requests with a New status
      could be given an Assigned or Resolved status by the Developer role.
      Those with an Assigned status could get a Resolved status. The status of
      all the other Bug type requests cannot be modified by the
      Developer.</para>
    </section>

    <section>
      <title>Enumerations</title>

      <para>The value lists used by the application can be customized (for
      example, setting Issue priorities). This screen allows you to define the
      possible values for each of the following lists:</para>

      <itemizedlist>
        <listitem>
          <para>Issue Priorities</para>
        </listitem>

        <listitem>
          <para>Document Categories</para>
        </listitem>
      </itemizedlist>

      <para></para>
    </section>

    <section>
      <title>E-mail notifications</title>

      <para>This screen allows you to select the actions that will generate an
      e-mail notification for project members.</para>

      <para>Note: E-mail sending must be activated in the application
      configuration if you want to make any notifications.</para>
    </section>

    <section>
      <title>Authentication</title>

      <para>By default, redMine refers to its own database to authenticate
      users, by a specific password.</para>

      <para>If you already have one or several external user references (like
      LDAP), you can make them known in order to be used for authentication on
      redMine. This allows users to access redMine with their usual user names
      and passwords.</para>

      <para>For each known reference, you can specify if the accounts can be
      created on the fly on redMine. If needed, the user accounts will be
      created automatically during the user’s signing in (without any specific
      rights on the projects), according to information available in the
      reference. Otherwise, the administrator must have previously created the
      user account on redMine.</para>

      <para></para>

      <section>
        <title>LDAP statement</title>

        <para></para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">Name</guilabel> : reference
            display name</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Host</guilabel> : LDAP server host
            name</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Port</guilabel> : connection port
            to the LDAP server</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Account</guilabel> : DN of the
            connection account to LDAP (please leave it blank if the directory
            authorizes anonymous read access)</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Password</guilabel> : password of
            the connection account</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Base DN</guilabel> : Basic DN used
            for user search in the directory</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">LDAP screen</guilabel> : User
            search screen in the directory (optional)</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">LDAP features</guilabel> :</para>

            <itemizedlist>
              <listitem>
                <para><guilabel moreinfo="none">Identifier</guilabel> : LDAP
                feature name used as user identifier (e.g.: uid)</para>
              </listitem>

              <listitem>
                <para><guilabel moreinfo="none">First name</guilabel> : LDAP
                feature name including the user’s first name (ex:
                givenName)</para>
              </listitem>

              <listitem>
                <para><guilabel moreinfo="none">Last name</guilabel> : LDAP
                feature name including the user’s last name (ex:
                familyName)</para>
              </listitem>

              <listitem>
                <para><guilabel moreinfo="none">E-mail</guilabel> : LDAP
                feature name including the user’s e-mail address (ex:
                mail)</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para>The features" <guilabel moreinfo="none">First name</guilabel> ",
        " <guilabel moreinfo="none">Last name</guilabel> " and " <guilabel
        moreinfo="none">E-mail</guilabel> " are not used except when the
        accounts are created on the fly.</para>
      </section>
    </section>

    <section>
      <title>Information</title>

      <para>Displays application and environment information.</para>
    </section>
  </chapter>

  <chapter>
    <title>Projects</title>

    <section>
      <title>Project overview</title>

      <para>The overview presents the general project information, its main
      members, the latest announcements, as well as an synthesis of Issue
      requests open by tracker.</para>

      <para></para>
    </section>

    <section>
      <title>Planning</title>

      <para></para>

      <section>
        <title>Project calendar</title>

        <para>Project calendar shows the tasks that begin or end during the
        selected month (current month by default). An issue will be displayed
        as a task if its start date and its due date are specified.</para>

        <itemizedlist>
          <listitem>
            <para>This symbol <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/arrow_from.png" />
                </imageobject>
              </inlinemediaobject> represents a task that begins</para>
          </listitem>

          <listitem>
            <para>This symbol <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/arrow_to.png" />
                </imageobject>
              </inlinemediaobject> represents a task that ends</para>
          </listitem>

          <listitem>
            <para>Ths symbol <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="images/arrow_bw.png" />
                </imageobject>
              </inlinemediaobject> represents a task that begins and ends the
            same day</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>

      <section>
        <title>Gantt chart</title>

        <para>This diagramme shows tasks and their achievement rate.</para>

        <para>Achievement is represented in blue. Delay in red.</para>

        <para></para>

        <screenshot>
          <screeninfo>Gantt chart</screeninfo>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/gantt.png" />
            </imageobject>
          </mediaobject>
        </screenshot>
      </section>
    </section>

    <section>
      <title>Issue management</title>

      <para></para>

      <section>
        <title>Issue list</title>

        <para>By default, the entire list of the project open Issues are
        displayed. Various screens allow you to select the Issues to be
        displayed. If the project has sub-projects, you have the possibility
        to display the sub-project's Issues as well (not displayed by
        default).</para>

        <para>Once applied, a screen is valid during the entire session. You
        can re-define it or delete it by clicking Cancel.</para>

        <para></para>

        <screenshot>
          <screeninfo>Request list</screeninfo>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/issues_list.png" />
            </imageobject>
          </mediaobject>
        </screenshot>

        <para></para>
      </section>
    </section>

    <section>
      <title>Reports</title>

      <para>This screen presents the number of Issues and Issue status
      synthesis according to various criteria (tracker, priority, category).
      Direct links allow for access to the detailed Issue list for each
      criterion.</para>
    </section>

    <section>
      <title>Change log</title>

      <para>This page presents the entire list of the resolved Issues for each
      version of the project. Certain types of Issues can be excluded from
      this display.</para>
    </section>

    <section>
      <title>News</title>

      <para>Allows you to inform users on project activity.</para>
    </section>

    <section>
      <title>Documents</title>

      <para>Documents are grouped by categories (see Value Lists). A document
      can contain several files (for example: revisions or successive
      versions).</para>
    </section>

    <section>
      <title>Files</title>

      <para>This module allows you to display various folders (sources,
      binaires, ...) for each version of the application.</para>
    </section>

    <section>
      <title>Settings</title>

      <para></para>

      <section>
        <title>Project features</title>

        <para></para>

        <itemizedlist>
          <listitem>
            <para><guilabel moreinfo="none">Public</guilabel> : if it’s a
            public project, it can be viewed (request consultation, documents
            consultation, ...) for all the users, including those who are not
            project members. If it’s not a public project, only the project
            members have access to it, according to their role.</para>
          </listitem>

          <listitem>
            <para><guilabel moreinfo="none">Customized fields</guilabel> :
            Select the customized fields that you want to use. Only the
            administrator can define new customized fields.</para>
          </listitem>
        </itemizedlist>

        <para></para>
      </section>

      <section>
        <title>Members</title>

        <para>This screen allows you to define the project members as well as
        their corresponding roles. A user can have only one role in a given
        project. The role of a member determines the permissions they have in
        a project.</para>
      </section>

      <section>
        <title>Versions</title>

        <para>Versions allow you to follow the changes made during all the
        project. For instance, at the close of an Issue, you can indicate
        which version takes it into account. You can display the various
        versions of the application (see Files).</para>
      </section>

      <section>
        <title>Request categories</title>

        <para>Issue categories allow you to organize Issues. Categories can
        correspond to different project modules.</para>
      </section>
    </section>
  </chapter>

  <chapter>
    <title>User accounts</title>

    <para></para>

    <section>
      <title>My account</title>

      <para></para>

      <section>
        <title>Information</title>

        <para>This screen allows you to modify your account: lastname,
        firstname, email address, language.</para>

        <para>If <guilabel>Mail notifications</guilabel> is unchecked, no
        email will be sent to you.</para>
      </section>

      <section>
        <title>Password</title>

        <para>To change your password, type your old password and your new
        password (twice). Password length must be between 4 and 12
        characters.</para>

        <para>If your account uses an external authentication (LDAP), you
        can't change your password in redMine.</para>
      </section>
    </section>

    <section>
      <title>My page</title>

      <para>This page allows you to display various information about your
      projects.</para>

      <para>To personalize your page, click on <guilabel>Personalize this
      page</guilabel>. Then you can choose which information to display and
      where it is displayed.</para>
    </section>

    <section>
      <title>Password lost</title>

      <para>If you loose your forget, a procedure allows you to choose a new
      one.</para>

      <para>On the login screen, click on <guilabel>Lost password</guilabel>.
      Type your email address and submit the form. An email is then sent to
      you. It contains a link that allows you to change your password.</para>

      <para>If your account uses an external authentication (LDAP), this
      procedure isn't be available.</para>
    </section>

    <section>
      <title>Register</title>

      <para>By registering, you can get an account without the intervention of
      the administrator.</para>

      <para>On the login screen, click on <guilabel>Register</guilabel>. Fill
      the form and submit it. An email will be sent to you. To activate your
      account, use the link that is contained in this mail.</para>

      <para>The possibility to register can be desactived in the application
      configuration.</para>
    </section>
  </chapter>
</book>