Rifidi Developer's Guide

Introduction

Thank you for your interest in the Rifidi project. While we are glad that you decided to join the community, there are a number of standards that we expect our members to adhere to. Whether it is filing a bug report or submitting patches, there is a need for a set of guidelines so that high quality work is submitted.

Back to Top

Rifidi Bug Tracker

First Time Users

Please read the “Getting Started” section of this document thoroughly before submitting any defect reports or feature requests. Doing so will save both you and RiFiDi project contributors time and possible frustration. Failure to follow guidelines set in the getting started section may result in potential bugs not being addressed as well as actions such as account termination and ban if the guidelines are repeatedly ignored.

Back to Top

Getting Started

Thank you for your interest in the RiFiDi project bug tracker. Defect tracking and feature requests are extremely important to the continued development and refinement of the product. However, there are a number of guidelines and procedures which must be followed in order for such tracking to be efficient and successful. The next few paragraphs will explain the desired defect submission process, as well as the general defect report life cycle.

Back to Top

Type of Users

• Reporter - Lines them up

  A reporter is any user who can file bug submissions. They are typically not involved in the coding effort though they play a significant role in assisting developers with identifying problems and verifying results. While it is not required of reporters, it is highly desired that the submitter provides final sign-off on an issue's resolution. Generally, a reporter user will be able to access the Subversion repository, but will not be able to commit changes on their own. If a reporter consistently provides quality issue submissions and/or insight in to issue resolution, they may be asked to join as a tracking manager or developer.

  Back to Top

• Developers - Knocks them down

  Developers are the users who resolve the issues which are filed, whether it be enhancements or defects. A developer will also post updates on such issues, indicating when progress has been made, as well as any problems which arise during resolution. Developers generally have commit access to the Subversion repository, and thus can directly provide fixes. It is important to note that developers are considered to be reporters as well, and are expected to submit defect reports and feature requests in the same manner as reporters.

  Back to Top

• Issue Tracking Managers - Cleans up the Mess

  Power Users are users who act as administrators for the project. They assign issues in the bug tracker to appropriate members of the development team. They are also responsible for keeping the bug tracker clean. This involves identifying and removing duplicate issues, issues which are impossible to reproduce or severely lacking in documentation, and issues that are simply are not feasible to resolve. They may also act on behalf of others to close issues which have been verified as resolved.

  Back to Top

Creating a User

To create a user, browse to the RiFiDi Mantis Bug Tracker located at http://www.rifidi.org/mantis/. There, one may register for a new account by clicking the “Signup for a new account” link located under the login menu. Only a username and valid email address are required to register for an account. After registering, an email confirmation will be sent containing a link to activate the registration. Once this activation is complete, the user can log in using the password sent in the confirmation email. This user may now login to view current and past issues, as well as submit new issues to the tracker. All users created are initially of the reporter type, but can progress rapidly based on their contributions and skills.

Back to Top

Defect/Feature Submission

Before submitting any issues, it is the responsibility of the submitter to make a good-faith effort to ensure that the same defect/feature has not already been submitted. Duplicate submissions cannot always be avoided, but every attempt at avoiding them results in huge time savings for everyone involved.

Once it has been determined that the issue should be submitted a report should be filed. Although contributors may submit reports on their own, it is desirable that the issue is confirmed by another developer in the project before being submitted. Having another member verify that the defect exists can help to spot any potential duplicates, and to be absolutely sure that the bug is reproducible. This may be done by simply sending an email to the project mailing list and receiving confirmation that others have experienced the same concerns.

To submit a bug report, click the “Report Issue” link when logged in to Mantis. Pick the appropriate package category (or one of the general categories if they are better suited), how well the bug may be reproduced, and its severity. Try to give a clear and concise title for the bug. A title such as “Crashes” is not very useful. A title such as “ReaderGUI – JVM Crashes on Tag List Clear” is much more descriptive and has the benefit of making it easier for others to avoid submitting duplicates. In the description section of the bug report, a detailed explanation of the problem encountered, along with any steps to reproduce the bug should be given. Finally, in the additional information section, supporting material such as a stack trace or debugging statements may be given as reference. Screen captures, log files, and other articles may be attached to the report by using the Upload File field.

Back to Top

Sample Issue Submission

Back to Top

Defect/Feature Tracking

Once the bug report is submitted, it will be flagged as open with no owner. The Issue Tracking Manager for the project or other developers with managing rights will assign the bug to the proper owner. Once the owner fixes the bug, or cannot continue without assistance, they will reassign the issue to another project member. This new owner may then fix the bug on their own, provide information on how to fix the issue, verify that the defect is fixed, or a number of other actions.

This process of reassignment continues until the bug has been verified as fixed and the source code is checked into version control. Once this occurs, the issue may be closed by either the original submitter or another with appropriate privileges.

The tracking manager may close issues that the community and developers feel are no longer relevant.

Back to Top

Resources

RiFiDi Bug Tracker Page: http://www.rifidi.org/mantis/

Mantis Page Descriptions: http://manual.mantisbt.org/manual.page.descriptions.php

RiFiDi Subversion Repository Browser: http://svn.sourceforge.net/viewcvs.cgi/rifidi/

Back to Top

General Development

Coding Standard

The Rifidi project expects all project developers to follow the Sun® Code Conventions for the Java Programming Language. This gives both general and specific guidelines for creating code which easy to read and maintain. A copy of the document may be obtained at http://java.sun.com/docs/codeconv/. Each source file must also contain a license header at the beginning of the file. An example of this can be found in any of our source files.

Back to Top

Source Control (Subversion)

Location

The location of the project's subversion repository is https://svn.sourceforge.net/svnroot/rifidi. This address may be used with any software which can interact with Subversion repositories. To browse the repository using a web-interface, point your browser to http://svn.sourceforge.net/viewcvs.cgi/rifidi/.

Back to Top

Submitting Patches

If you do not have direct commit access you must submit patches for review. If the patches are seen to be of high quality, they will be placed into version control.

Back to Top

Committing

Those with direct commit access to version control may check in patches at any time. Despite this, it is desired that any commits which are not directly related to a issue in the bug tracker be discussed with other members in the project.

When committing, it is essential that a informative comment be placed along with the commit. Each commit version should summarize what was done with the files committed. This helps give another method to track progress within the project. Also, it helps when tracking down any regressions that may occur.

Back to Top

Obtaining Commit Access

Commit access is obtained through invitation only. The members of the community with commit access will motion for a vote to give a selected member commit privileges. The requirements for a successful vote are not yet established, although a unanimous vote will generally lead to giving commit access.

Back to Top