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 email@example.com.
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
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
- RTT Ready for Testing, set by the developer when finished
Being tested, set by the Testing Coordinator when assigned to a
- 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
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
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
18.104.22.168. Checking out
22.214.171.124. 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.1. In the PR System
4.2. Major Releases
4.3. Minor Releases