SDM Design Documentation

I. Essentials

• User directory: /sdm
• Sitewide administrator directory: none
• Data model: /packages/sdm/sdm.sql
• Requirements document: /arsdigita/doc/requirements/sdm.html
• Design document: this file...
• Page Flow: /arsdigita/doc/page-flow/sdm_interaction_admin and /arsdigita/doc/page-flow/sdm_interaction_users
• ER Diagram: /arsdigita/doc/er-diagrams/small_sdm_er

II. Introduction

The Software Development Manager (SDM) is a web-based application that, as the name suggests, helps manage the development of software projects. Based on a software-centric data model, the SDM provides functionality such as bug reporting, bug tracking, and release management. For the project coordinator, SDM is a way of staying on top of a project's status. For the developer, SDM let's them know what bugs need to be fixed and which features must be implemented. For the end-user, SDM is a feedback mechanism for reporting bugs and a source of information for downloading releases.

III. Historical Considerations

SDM is a unique ACS 3.x module in that it was primarily developed outside of ArsDigita. SDM was conceived by Philip Greenspun and Ben Adida and then implemented by Ben as part of OpenACS. In July of 2000 SDM was ported from the Postgres OpenACS version to Oracle by Dennis Gregorovic and Todd Nightingale. During this port the code was brought up to ACS 3.4 conventions and parts of the data model and user interface changed. However, the version of SDM used by ArsDigita today remains faithful to its OpenACS origins.

IV. Data Model Discussion

The data model for SDM is centered around four tables: sdm_packages, sdm_modules, sdm_package_releases, and sdm_tickets. Each of these tables represents a key "object" in the SDM system. These tables also reference each other and these references establish relationships between the objects. For example, tickets always belong to exactly one package, but may belong to zero or one module within that package.

Of course, these four tables do not make up the entire data model. There are more tables, views, and PL/SQL functions that are necessary for full functionality. Here are some of the more notable:

• Tables
  • sdm_package_admins provides a mapping of package administrators.
  • sdm_module_users provides a mapping of module users.
  • sdm_ticket_status provides a list of valid status ticket values.
  • sdm_ticket_severity provides a list of valid ticket severity values.
  • sdm_ticket_ratings keeps track of user ratings for each ticket.
  • sdm_ticket_assignments provides a mapping of who is assigned to each ticket.
  • sdm_user_ticket_interest_map provides a mapping of who is interested in each ticket.
  • sdm_user_package_interest_map provides a mapping of who is interested in each package.
  • sdm_notifications keeps a listing of package and ticket change notifications.
  • sdm_notification_prefs keeps track of each user's notification preferences.
  
  
• PL/SQL Functions
  • sdm_user_can_edit_release_p is used to determine if a user can edit a release. There are similar functions for editing and viewing packages and modules.
  • sdm_release_lessthan_p is used for comparing release versions.
  • sdm_ticket_assigned produces a list of users assigned to a particular ticket.
  • sdm_package_add_notification adds a notification to sdm_notifications for a particular package.
  • sdm_ticket_add_notification adds a notification to sdm_notifications for a particular ticket.
  • sdm_tickets_notification_tr is a trigger on sdm_tickets that automaticaly adds notifications when tickets are modified.

V. Legal Transactions

Users may

• Add tickets

• Add packages

Users may

• Edit ticket status, severity, expected completion, type, and description
• Add and Edit notification preferences
• Add ticket assignments

• Edit packages
• Edit all ticket information
• Add and Delete package admins
• Add and Delete module users
• Add, Edit, and Delete modules
• Add and Edit package releases
• Add and Delete ticket assignments

VI. API

sdm_url_stub {}

The URL for content under the application. Defaults to "/sdm"

sdm_software_root {}

The directory where uploaded software is stored

sdm_version {}

The version of the module

sdm_notification_sender_email {}

The email address to be placed in the 'From' field for notification email.

sdm_home_context_bar_item {}

Context bar item for the home page of SDM

sdm_module_context_bar_item {module_id module_name}

Context bar item for specified module

sdm_package_context_bar_item {package_id package_name}

Context bar item for specified package

sdm_package_release_context_bar_item {release_id release_name}

Context bar item for specified release

sdm_header {title}

Default header HTML for application pages

sdm_footer {}

Default footer HTML for application pages

sdm_system_name {}

Name of the SDM system

sdm_default_severity {}

Returns the default ticket severity

sdm_list_of_ticket_types {}

Returns a list of ticket types

sdm_list_of_severities {}

Returns a list of severity options

sdm_list_of_notification_prefs {}

Returns a list of notification interval preference options

sdm_ticket_status_id {ticket_status}

Returns the ID of the specified ticket status

sdm_severity_id {ticket_severity}

Returns the ID of the specified ticket severity

sdm_return_access_complaint {}

Returns an access violation error page to the user

sdm_check_admin {}

Checks where the current user is an SDM administrator

sdm_verify_admin { conn args why }

A filter that only passes for SDM admins

sdm_user_can_add_packages { user_id }

Checks whether the user has permission to add packages

user_can_see_package_p { user_id package_id }

Checks whether the user has permission to see the specified package

user_can_see_module_p { user_id module_id }

Checks whether the user has permission to see the specified module

user_can_edit_package_p { user_id package_id }

Checks whether the user has permission to edit the specified package

user_can_edit_release_p { user_id release_id}

Checks whether the user has permission to edit the specified release

user_can_edit_module_p { user_id module_id}

Checks whether the user has permission to edit the specified module

make_user_select_html { sql_query {name user_id}}

An HTML widget that create a selectable list of users from the query

sdm_valid_status_transitions {}

Returns a list of valid ticket status transitions

sdm_valid_transitions { start_state}

Returns a list of valid ticket status transitions for the given start state in the current stack frame<

sdm_transition_is_valid_p { transition }

Checks whether the specified transition is valid

set_simple_user_information {}

Sets the folllowing user information variables: user_id, user_logged_on_p, first_names, last_name, email

set_simple_module_information { module_id }

Sets the following module information variables: module_name, package_id, package_name, package_private_p, module_private_p

set_simple_package_information { package_id }

Sets the following package information variables: package_name, package_private_p

sdm_software_dir { package_id release_id {module_id ""} }

Returns the directory path for the specified release

sdm_release_filename { release_id original_filename }

Returns the filename for the release

sdm_cleanup_filename {filename}

Removes extra characters from filename

sdm_code_license {}

Returns the license for uploaded code

sdm_download_package_release { ignore }

Serves a package release file

sdm_user_has_rated_ticket_p { user_id ticket_id }

Returns 1 if the user has rated the ticket, 0 otherwise

sdm_rate_ticket { user_id ticket_id rating }

Enters the user's rating for the ticket into the database

sdm_ticket_rating { ticket_id }

Returns the average rating for the ticket

sdm_ticket_n_interested_users {ticket_id }

Returns the number of users interested in the ticket

sdm_ticket_user_is_interested_p {ticket_id user_id }

Returns 1 if the user is interested in the ticket, 0 otherwise

sdm_ticket_user_is_interested {ticket_id user_id }

Registers the user as being interested in the ticket

sdm_ticket_user_is_not_interested { ticket_id user_id }

Registers the user as not being interested in the ticket

sdm_package_n_interested_users { package_id }

Returns the number of users interested in the package

sdm_package_user_is_interested_p { package_id user_id }

Returns 1 if the user is interested in the package, 0 otherwise

sdm_package_user_is_interested { package_id user_id }

Registers the user as being interested in the package

sdm_package_user_is_not_interested { package_id user_id }

Registers the user as not being interested in the package

sdm_ticket_notify { what ticket_id subject body {excluded_users {}}}

Immediately notifies relevant users of an action performed on a ticket

sdm_notify_users_ticket { ticket_id notification }

Adds the notification for the specified ticket into the notifications table

sdm_notify_users_package {package_id notification }

Adds the notification for the specified package into the notifications table

sdm_send_one_email {to from subject body}

Send an email with an SDM footer after the body

sdm_send_notifications { interval }

Sends email out for notifications

sdm_remove_notifications { interval }

Clears out old notifications from the database

VII. User Interface

• There is a 'My SDM' page which lists packages and releases managed by the user in addition to all tickets opened by or assigned to the user.
• There are links on every page to 'My SDM' and 'Help'.
• The user can see a list of all oustanding or resolved bugs and feature requests in a package.
• The user can sort this list by ticket ID #, rating, #interested, severity, module, assigned to, expexcted completion, or summary.
• The page which displays the details of a single ticket is divided into two sections - 'community' and 'feature information'.
• These community aspects are reflected in other places, such as the # interested column in the ticket listings.

VIII. Configuration/Parameters

[ns/server/service_name/acs/sdm]
; Do we allow users to comment on tickets?
SolicitCommentsP=1
CommentApprovalPolicy=open
UrlStub=/sdm
; This is where uploaded tarballs are stored
SoftwareRoot=/web/my_service/sdm-software
SdmVersion=1.0
NotificationSenderEmail=webmaster@yourdomain.com
SystemName=Software Development Manager
DefaultSeverity=medium

IX. Acceptance Tests

• Create a package. *
• Change the package description and package name. *
• Create a module in the package. *
• Change the module description, module, name, and module owner. *
• Create a release for the package. *
• Change the version of the release. *
• Create a ticket in the package but not associated with a module.
• Create a ticket in the package and associate it with a module.
• Change the severity of the ticket.
• Change the description of the ticket.
• Change the type of the ticket.
• Set the expected completion for both tickets.
• Assign a ticket to yourself.
• Assign a ticket to someone else.
• Mark a ticket as fixed. Verify that the ticket submitter and users assigned were notified.
• Make the release live. Verify that the open ticket is listed. *
• Create another release. *
• Take back the first release and make the second one live. *

X. Authors

• System creators: Philip Greenspun, Ben Adida
• System owner: Dennis Gregorovic
• Documentation author: Dennis Gregorovic