Project Dune:UserGuide
From PDune
How to use Project Dune
For stable installations
Copyright © 2007 Gerard Toonstra, under the Creative Commons Copyright, ND-AT
Contents |
Note: A previous HTML version of this document is available here
Preface
Before you begin
After you've downloaded Project Dune, the first job is to install it. See Project Dune Forums to get that information from the installation guide.
A very important point on the efficient usage of Project Dune is the understanding of its configuration and customization. The configuration can be done with the administration module. There you can set the available statuses, severities and other kinds of information. Not all important settings or workflows can be customized from the administration module. For very specific requirements, you should edit some database tables directly. For information how to manipulate those tables, please stop by at the Project Dune Forums. Besides the main configuration tables, there's a CONFIGPARAMETER table that is mostly used to change the behaviour of the software.
Project Overview
Project Dune is written for managers, developers, release engineers, quality assurance officers, testers and configuration engineers. It has two main objectives:
- To automate routine tasks for those people using the software, or to make their tasks more efficient.
- To prevent the loss or obstruction of information and meta-data between teams or inbetween development stages.
What Project Dune can do
Project Dune manages issues, project information, documents, estimates, inspections, tasks, timesheets and test results. At the moment, this covers the entire software development life-cycle needs for small to medium projects. Besides some innovative features to enter data into the database, the most important feature of information systems is the ability to retrieve information. This project uses the generation of reports to do that.
All of the modules in the project use web2.0 technology (AJAX). This should ensure quick responses from the server and very quick editing times for your users of the software for a number of reasons.
Feature OverView Descriptions
General navigation
After you've installed the project, you should be able to access the site by a url that looks like the following: http://>host<:>port</dune. You'll be presented with the main Project Dune webpage and an option to log in at the top right.
Issues, projects, releases and other things can generally be listed with a paged list component. It looks the same for each item, but it will have different headers at the top. Using the buttons at the top right, you can navigate between the pages. There's a button and a number field in the same grey navigation bar that can be used to set the number of items listed.
Next to this setting on the left, there's a link to a filter dialog where you can set and save filters that you can reuse at any other point in the future, as they are persisted in the database.
There's a wide navigation bar at the top with a dropdown menu that is used to navigate to other parts of the application.
Workload management
Issue management
The issue is possibly the most important entity of this project management software. Issues are gaps, bugs, feature requests or other things. In short, pieces of work that are analyzed and/or acted upon later in the project. Scrum tasks are created for issues, but more about task management later. Issues have some customizable parameters like the status, severity and ownership. The way how the status, severity or ownership of issues are set can be customized through the customizable functions in the dune-custom package.
Throughout the project, you'll only gain access to those issues that belong to projects you have access to. Besides logging an issue on a project, you'll also need to allocate it against a scope statement in a release. This will allow you to run the effort verification reports later, as otherwise you'll not have the full information available on the work that is executed in the project.
Consult the administrator for more information on the types of issues that you can create, how to develop a workflow solution for managing severity and status for a certain project and so on.
Issue Feeds
At the top of the screen are links to issue (Atom 1.0) feeds that can help to keep track of recently changed issues more quickly. If you have a browser or feed reader that can interpret the format of Atom 1.0, you can subscribe to the channels. Be aware that for security and for ensuring you'll only see the updates for issues you should have access to, you have to use a feed reader that can log on (not all feed readers can do this).
- http://>host<:>port</dune/atom/issues/updated. This feed contains the most recently updated incidents to which you have access. That means those incidents that are created on projects that you are allocated to.
- http://>host<:>port</dune/atom/issues/journals. This feed contains the issues to which you have access, that have had new journals added.
Task management
Tasks are more granular pieces of work after an issue has been analyzed further. A task should generally not exceed a single day to comply with the instructions of Scrum task management. Only managers of a user attributed to a certain task may transfer the task to another person, or the person himself.
Each task has an hours detailed estimate. It is not required to be used, but it may help you to analyze your project life-cycle at a later stage if you have troubles maintaining your deadline or developing good estimates. The status of a task has five different settings:
- To do: The task can be picked up by someone.
- In progress: The task is being handled by someone.
- Finished: The task is finished.
- Impeded: The task is impeded and should be handled by the scrum master.
- Out of impediment: The task is out of impediment and can be picked up by someone.
Scrum task management
Task management in Project Dune is implemented based on the SCRUM vision and paradigm.
The Scrum module is relatively simple. It has a list to list and manage tasks and a Task edit panel. Depending on your role and group, you may reassign tasks or pull tasks towards yourself. The task management screen of Scrum resembles a task editing board. It is divided into five groups:
- To be done
- In progress
- Done
- Impeded
- Out of impediment
By switching between these boards, it is possible to get a quick oversight of the tasks that are available for you or the rest of your team.
Release management
You can plan releases in release management. Release management is part of project planning in Project Dune. If you wish to keep control of your project, you'll need to identify the scope of a release. This scope is identified in release management. After the scope is clear, you'll start creating and associating issues to this.
Each release has an identifier, so that it can be referred to later. Releases are important for issue, estimate and test management. Each of these entities is associated with a release one way or another.
If you keep good control of your releases and their associated entities, the reports available in the tools menu will be of great help to maintain that control further. Those reports should give you real-time information into the development process and progress.
Estimate management
Estimates are the starting points of your project. An estimate is only useful after you've sufficiently defined the scope of a software release. The scope is documented in the scope statements on the release. You'll see that each scope statement has separate simple estimates for each activity type, you're not meant to actually use them before you've applied a methodological approach to the estimation exercise.
The estimation module uses the Cocomo II model for its development. This is a rather mathematical approach to estimations and it is based on the input of about 150 projects for which mathematical analysis is applied. You'll probably find that the factors that accounted for those projects are very different from the factors in your industry or customers. Therefore, you shouldn't expect to use the Cocomo estimate module directly and produce correct results.
- You should make sure you have sufficient knowledge of the underpinnings of Cocomo II estimates in order to use this module efficiently.
Timesheet management
The timesheet is used to record your time spent on each task. Without Scrum management, you cannot make use of this module. It has three main views, which show the allocations by day, week or month. The top of the screen has navigation buttons to move from the current date to other dates in the future or in history.
The timesheet allows any user to create "timed activities". These are basically the allocation of hours against a certain scrum task, further detailed by the allocation of a certain activity type. The activity type helps you later on to find out how much time was needed for each phase of the development life cycle. It is possible to create many timed activities against a single task and the activity types may also differ for each timed activity. The activity type is thus not bound to the task itself, but freely chosen.
The project manager determines when the timesheet is submitted. This may be daily, weekly or monthly. The project managers can use a notification job in the DUNEJOB table to automatically send out email to users that have incomplete timesheet items. When the user submits a timesheet item, it cannot be edited any longer. The project manager needs to either approve or reject the remaining items. The project manager can individually approve timesheet items. When all items left to be approved are to be rejected, they can click the "Reject" button.
There is a flexible timesheet report available in the "Reports" section of Dune. This shows the allocated times for a certain user and it has many ways to group and filter on data.
Note that the "DuneBatch" process can extract the timesheets for you in an XML format. You can do this on a per-project basis. Those XML files can be used as an integration point with other systems, for example HR and financials.
Importing MS Project file
The project manager is responsible for the planning and execution of the project. Many projects use MS Project as a tool to plan tasks and activities, as soon as the WBS is done. (Although MS Project is helpful to do the actual planning, it is not a very good tool for keeping track of a project).
Scrum tasks in Project Dune can be quickly created from an MS project file. To do this, it must list the issue reference inside the task description at any point in that description. This issue reference must be demarcated by the characters '[' and ']'. Some examples are as follows:
Send email to user [PD-RF012] [PD-RF012] Send email to user Send email to user as described in [PD-RF012].
Note that the following task descriptions do not properly refer to the issue reference:
Send email to user: PD-RF012 Send email to user (PD-RF012) [PD-RF012 Send email to user (PD-RF012) Send email to user PD-RF012 Send email to user Send email to user
Meeting management
Meetings can be managed in project management. You can add a meeting in the project menu and select people that need to attend. The system sends out invitations and updates whenever the information changes. During or after the meeting, you can record the meeting minutes, which are sent to the invitees automatically (in HTML format).
Site/project administration
User settings
Through the user menu's, administrators can add new users and associate them with projects. The user detail panel consists of a couple of fields that should be easy to understand:
- The manager selection determines the user that is the manager of the user being created. The manager may manipulate entities in the project on behalf of the user. In the default configuration, the manager has certain privileges over issues and other items that the to be created user will perform in the system. For example, if the user creates an issue in the system and leaves or disappears, the managers can take or transfer ownership of that issue to another user.
- Special users may exist, which in turn have specific access permissions and other possibilities around the project.For example, there is a special "anonymous" user, which is used to determine the access permissions and other settings for those people that have not logged in into the website. The "admin" is another very special user, which isn't restricted to the visibility settings of other users. That is, if one is given the administrator role, they'll be able to access everything even if they are not associated with any project.
- The access group is used to define the fields, menu's and screens that a certain user has access to (or are determined mandatory for that user). This is basically a user's profile.
- The DUNE group is another grouping for the user, which is used to define inter-relationships between users as colleagues. This is also used for permission-management for entities in the system. For example, if a user is a colleague of another user, the rules may define that the colleague may perform certain functions on the issue that users outside the group are not able to do.
- The role is used for user selection. At the moment it defines for example the users that are project managers and only those users will be part of the selection box to assign new projects to (in the role of project manager). More uses for the other types of roles may be added in the future.
- The color is a descriptor in HTML hexadecimal notation (#FFFFFF), which is the color used for the inspections module.
- The photo is a 53x53 image in GIF, PNG or JPEG format that the user wants to allocate to his profile. This photo will show up during inspections.
Project management
When starting a new project in the organization, you'd typically create a new project and allocate this to the project manager in charge. The project itself never equates to a release, but it highly determines the visibility of issues and other entities for users. This is because users are associated with projects in the user management screens.
You should see a project entity in Project Dune as the evolution of a certain product. For this reason, the project has specific repository settings (the repository containing the full evolution from import up to the latest version with all branches, source control) and you can start planning releases for it. The project code is generally used in issue management to be able to distinguish issues from one another.
The user and pass settings for the repository access should be supplied by your configuration manager. The repository class is an internal class of the system that is responsible for interacting with the specific software product that the team is using. The system will only retrieve files or retrieve version information about files. Possible values for the repository class are:
- net.sf.pdune.custom.repository.CVSRepository
- net.sf.pdune.custom.repository.SubversionRepository
Later versions of Project Dune might use a selection box to make this configuration easier.
The URL settings for the repository depend on the type of software that is used and will be the same as that a programmer regularly uses. Subversion repositories do not need to check out a version on the server, since it uses the server link directly to download files and file information. For CVS, it is advisable to create a checked out directory on the server for each project. Note that the server will however use the server link directory to download files and file information.
Reports
The reporting functionality in Project Dune is a very powerful and an extensible, as well as customizable framework. The reports depend very strongly on XML and XSLT technologies. The reports that can be generated range from issue lists or summaries to effort verification reports to timesheet reports.
Each report has a different set of fields that can be supplied as input parameters. These will appear automatically. For some reports, you can even set the grouping of the items. If you wish to modify the reports, adjust colors or other functions, look into the "xsl/reports" directories and look into the "DuneCustom" package for the report aggregators and handlers.
Importing requirements
The requirements document in OpenDocument format can be imported to quickly create a starting hierarchy of issues, so that you can quickly get up to speed. Since it's very unlikely that the structure of the requirements document matches your needs, it's very likely that you'll end up manipulating the import stylesheet.
How to structure the requirements document
Project Dune can only import documents that are in Open Document format. This is the default format for OpenOffice.org, but MS Word should also be able to export to that format, as it is governed by Oasis. This format is not to be confused with Microsoft's "Open XML" format, which is basically a backwards-compatible sub-standard that contains tags going back to WordPerfect times, which is an editor in use about twenty years ago.
The actual import and recognition of requirements is done through the use of an XSL file, reqdocument.xsl. This file is available in the distribution and was written for testing purposes. If you need to deviate from the default convention, then you may have a chance to make modifications there.
The proper way to have requirements recognized is to start them with RF and make them cross-references in the document. This will make the system recognize the requirement. If the cross-reference starts with any other set of characters, it will be ignored.
When the document parses thus encounters any bookmark (cross-reference) it will add this to an internal list and look for any references to other potential bookmarks. If the document author adds bookmark references after the text, the parser will add those references to the list as dependent issues. So, for example, if a text is written as follows ("bookmark" is where the document author selects the text to be made a bookmark. The "x-ref" is an inserted reference to that bookmark):
[<bookmark>RF012</bookmark>] Send email to user
References: <x-ref>RF013</x-ref><x-ref>RF014</x-ref>
When the user has subscribed to the channel, as described in
<x-ref>RF015</x-ref>, the user will ....
This will create an issue named "PC-RF012", which will be automatically associated with "PC-RF013", "PC-RF014" and "PC-RF015". In this example, "PC" is the project code for the project, which is the project that these requirements are part of.
- The use of a project code is enforced in the default distribution of the software and can be changed in the customization package.
The final step of the import is the verification of the issue infrastructure that is created. This function here should help significantly to reduce the time to create an infrastructure in an issue management tool to start managing the implementation of requirements. Together with the project import, this enables a very quick startup time for the project so that there is more time to spend on other more productive things.
Document management
Project Dune contains a document management module (DuneWrite). This module allows you to to write your documents using a web interface, thus in standard HTML. The benefits are as follows:
- It stores document fragments in a database, so it's possible to relate other items to those elements separately.
- The document elements can be converted into DocBook, which allows further conversion into HTML or PDF
- There is no direct formatting applied to the text, so that when your styles change, the text will be formatted according to the new styles. This may be very important for company takeovers or growing companies that spend time on better design of templates later.
- In the future, Project Dune will add functionality for document workflow.
- Maybe you won't need expensive office software for writing documents, saving on license costs.
- Your documents stored this way won't suffer or be lost due to viruses.
- Document authors in general store a local copy of the document on their machine for a determined amount of time. Using this solution, the document exists in the database everyone always has access to the very latest of edits.
- The system sends notifications to people when elements of a document change. This way, your functional authors don't need to remember to notify people of certain changes.
The documents can be versioned and extracted in PDF format later using the functions available in the document list.
QA management
Inspection management
Inspections are always created automatically on a source-code check-in. The inspection entity is highly coupled to a particular issue through the comment log statement. The comment log statement should contain the issue reference, followed by free text:
[[PD-RF012]: Added feature 'x' to the screen panel.
When the user clicks the external link to perform the inspection, a separate window appears with the code that was checked in, where text can be selected for making comments. Notice that in this same window, other comments also appear for files that other inspectors have already inspected. The photo and color used in the inspections is dependent on the user management screens.
After the inspection is completed, the inspector can close the screen and request the moderator to update the status of the inspection to the next stage. As soon as the inspection is set to "completed", nobody can add or delete any comments and the author needs to use the system to perform his rework. The author should indicate for each inspection comment whether it was agreed and whether the requested changes were made. If the changes were not made, a justification should be added.
When the moderator receives the OK from the author, the moderator needs to check the rework that has been done and can then "sign off" the inspection as having been completed entirely.
Test management
Testers will generally use the test module to manage their information. This module allows testers to write test case for a certain project. The test cases are written in rich text to make it clearer during the execution phase. If a certain test case no longer applies, you can mark it as inactive, so that it doesn't get used in a next (new) test run.
When all test cases are written for a test run, it's possible to create a new run. This will use the current date and time as the execution date/time. As the test run is created, it will pre-create results in the state of "not executed". Each test result refers to an active test case of the project at the time of creation. For that reason, you should (and only have to) create a test run just when you're about to start testing.
- To make testing easier, you can export the entire test script for those test cases that are to be executed using the "View PDF" button. This button is available from the test run edit panel.
