APT Development Procedures

[DRAFT updated 9/14/07]

This document outlines the procedures and processes used in managing the APT workload throughout the development life-cycle.  We aim to have a light process, but it is important to understand the whole workings of the system in order to be able to handle issues that may be outside of the normal.

1. Problem Reports - What they are and how they are used

The core work unit within APT development is the Problem Report or PR.  These are archaically referred to as OPRs as well.  A PR is necessary to document all changes that are made to the system and communicate their current state in the development process.  All PRs are tracked using the PR System, which is a homegrown defect reporting/management system maintained by STScI personnel.  It can be accessed at http://www.ess.stsci.edu/prsystem/.

1.1. Setting up your PRSystem account

You can set up an account on the PR System by emailing prsys@stsci.edu.  Your user id will be the same as your email account ID.  You will need a password, and can set up certain account features as you like.  There are a few features that need to be set to support APT development and communication.  These are available under the Edit account option.

Notify Assignees should be set so that if you assign a PR to someone, they will receive email.

Susbsystem Picklist can be left blank, but it is better to choose only those systems you will interact with.  For APT development, these include all the APT and APT- systems, as well as DG, PCTOOLS, PHASEONE, PP, and PROPINST.  We are responsible for all of these systems and need to be aware of PRs on all of them.  [Note: PROPINST is not maintained by us, but is prioritized through our meetings, and often influences APT PRs.  PP and DG are set to be retired soon]

Assignee Picklist could be limited to the developers you interact with regularly, but the APT PR Coordinator needs to be able to assign to virtually anyone.

Next you will need to Edit Email Notifications.  This determines how often and for what reasons you will receive email about PRs.  These can be set to arrive ASAP, Hourly, Daily or Weekly, and assigned to any susbsystem, assignee, submitter, or state.  In general it is suggested that all developers receive ASAP notifications of PRs for which they are the assignee, and Daily notification of PRs modified that are part of Susbystems they support.  It is often useful also to be notified about PRs that the developer as submitted.

1.2. PR Tracking Fields

At this point it is possible to use the PR system to query for work that is to be done, or has been done.  The relevant fields that track PR progress through the process are State, Ranking, and Build Id.  Assigned to is used to track responsibility for a PR.  

The States progress chronologically:
    NOREC    has not been reviewed or approved at a User's Meeting
    OPEN        approved and prioritized for development
    ASSIGN    assigned to a developer for work, or to a system engineer if more information is needed
    RTT        Ready for Testing, set by the developer when finished
    TEST        Being tested, set by the Testing Coordinator when assigned to a Tester
    FAILED    Did not meet the requirements when tested
    PASSED    Meets the requirements
    LIEN        If testing is not complete, but code is delivered anyway (Rare)
    WITHDRW    Withdrawn - submitter agrees that this work is not necessary
    REJECT    PR will not be done for whatever reason
    CLOSED    Set only when the Build is delivered and Closed separately (See Builds below)

WTHDRW and REJECT are special states, and no PR in those states should have a Bulid ID or Assignee, nor can any code be checked into the system repository (see below) for those PRs.

The Ranking is a measure of how important the PR is.  The Priority is usually set by the submitter and has not been used in APT.  Ranking is set such that lower values are more important, as most reports support sorting on Ranking.  Typical Priorities for APT PRs are listed in the APT Meeting Agenda and online at http://apst.stsci.edu/apt/apt-admin/priorities.html.  In general, 100 level PRs are considered Critical and must be dealt with for the assigned Build.

Build ID is set to further guide the timing for work to be done.  The Builds are generally known well in advance, and have a particular purpose, so PRs can be assigned to a build to highlight it for inclusion at that time.  All PRs that are set to RTT or later must have a Build ID.  The Developer should set it, and if that does not happen, the tester should do so.  Normally this is set to the current development build.  Builds are numbered for the HST cycle, and then with a major release number (.0 through .5 or more), and if necessary, with a minor release number (.1, etc).  E.g. "APT 16.4.1" is the 4th major release for cycle 16, with a minor release.

1.3. Submitting a Problem Report

If anyone finds an issue with the system, he or she should file a PR, no matter how simple the fix might be or how obscure the case.  First it is important to check to see if this is a duplicate issue.  This can be done by Searching the PR system, looking for keywords in the title or description, or by talking with the developers and testers to determine if this has been reported before.  If not, the PR should be assigned to a subsystem and given a descriptive title.  The body should contain as much as possible of the information about how to recreate the problem, requirements for correct behavior, and references to any experts who have provided insight into understanding the issue.

1.4. Reviewing Problem Reports

All developers are expected to review problem reports nightly, to at least familiarize themselves with issues that are uncovered.  They can provide feedback by commenting the PRs if they have any insights, or even assign themselves if they feel they can proactively deal with the issue.

1.5. Prioritization Meeting

APT has a scheduled meeting every Monday at 10am in N310 conference room to go over the outstanding PR list and determine priority rankings.  This meeting is not held every week, but can be during particularly busy development times.  The PR Manager will send out an agenda announcing the meeting on the Friday before.

The agenda is as follows.  First any issues relating to APT or its place in the proposal processing process are discussed.  These can result in new PRs, or other discussion to clarify what needs to be done.  Then the PRs are reviewed.  They are broken into 4 categories, which are kept separate for historical reasons:  non-APT system NORECs, non-APT PRs that are in progress, APT NORECs, and APT PRs that are in progress.

In Progress PRs refer to those PRs that have been assigned and worked on prior to the prioritization meeting.  For the purpose of expediency, this can happen for important PRs.  Because they follow the rest of the development cycle, they will be set to priorities other than NOREC.  But they need to be given a proper priority to assure they have been approved, and that they are being given proper attention.  All of these PRs will have a Ranking of 0 until that is set after the PR Prioritization meeting.

Next we will discuss APT status, especially when nearing build time, to determine how developers are doing on meeting the schedule.  Finally, the schedule will be reviewed and updated.

1.6. PR Assignment

When a developer is assigned to a PR, he is set as the "Assigned to" party.  The priority lets the developer know how important it is to work on, and the Build ID will also indicate the timeframe.  Some PRs may be assigned without a Build ID.  In this case it is up to the developer to determine when to work on the PR.  Assignments may also be made to other persons when more requirements information is needed.  When that information is supplied, the PR is commented with the new information, and usually set back to NOREC so that it will come up again at the next prioritization meeting.  

When an Assignment is made, the developer will receive an email, and also will be able to search the PR system to find assigned PRs to work on.  The most common queries are found here:

2. Development Tasks

Every developer has several responsibilities in developing solutions for assigned PRs.

2.1. Requirements Analysis/Review

The developer is responsible for ensuring that the requirements are complete and of sufficient detail to develop a solution.  In some cases, notably GUI development, this may require iteration with someone who will provide final approval of the design.  It can also include talking with various interested individuals to determine the final requirements.  Requirements need to be balanced between customer needs, maintainability, and the overarching APT design.

2.1.1. Generating Customer Buy-in

It is sometimes necessary for the developer to convince some portion of the user base of the need for a particular PR.  It is important to know who the customers are so that they can be appealed to as needed.  

Testers, PCs, Phase I PIs, Phase II PIs, ISs, Commandos, Trans/CASM developers, Phaseone manager

2.2. Design Process

2.3. Implementation and Coding

2.3.1.     CVS and the repository Checking out Diffing Committing changes

2.3.2. Coding Guidelines

APT Java Coding guidelines are available at http://apst.stsci.edu/documents/CodeConventions.html.  These should be updated as our coding practices evolve.

2.4. Developer Testing

3. Test Phase

3.1. PR Testing

3.2. Interface Regression

3.3. Regression Test Suite


4. Builds

4.1. In the PR System

4.2. Major Releases

4.3. Minor Releases

4.4. Patches