PEGASUS Enhancement Proposal (PEP)

PEP #: 1

TITLE: Pegasus Project Enhancement Proposals - Guidelines and the Approval Process

Version: $Revision: 1.1 $

Authors: Karl Schopmeyer, Mike Day, Denise Eckstein

State: Draft

Type: Process

Vote:

Created: 27 July 2002

Version History:

1.0 Draft 27 July 2002 K. Schopmeyer

1.1 Draft 7 August 2002, K. Schopmeyer - Clean up comments from earlier discussions.

Abstract:

This document describes the requirements for a Pegasus Enahncement Proposal (PEP) document including the format requirements, editorial process, and review process to get these documents approved.

What is a PEP?

A Pegasus Enhancement Proposal is the core document for implementation of changes in the Pegasus environment. It defines the request for an enhancement/change to Pegasus and provides the place where the status of the approval and implementation of the change can be recorded.

This is the single point where changes are defined, approved, and recorded for Pegasus except for bugs.  It is the objective of the Pegasus steering committee that all changes to Pegasus be controlled by either 1) PEP or 2) Bugzilla number for bug fixes in the future.  In the future, each new version of Pegasus is really a list of PEPs.

Types of PEP Documents

We envision three types of documents:

  1. Project definition PEP that define a new or significantly updated feature or implementation of Pegasus.  A PEP is not the design documentation for the project.  It provides information necessary to allow adequate review of the proposed project and make decisions about its integration, time frame, priority , etc.  It allows the project to be approved and for the integration of the project into the pegasus development.
  2. An informative PEP that describes a design issue, or provides general guidelines or information to the Pegasus community.
  3. Process PEP defines Pegasus process, process changes, etc.  The definitions in this type of PEP can be mandatory on the community as defined in the document (example, this document).

The Project LifeCycle for a PEP

The project for a feature change goes through three stages: approval, implementation, and integration.

A project starts when a PEP is submitted to the Pegasus project. Proposals are submitted by emailing PEPsto the Pegasus PEP Editor. Whoever proposes a project is responsible for making sure it is properly implemented. A proposal without a committed implementer cannot be approved.

The Editor is responsible for numbering them, marking them with draft status, putting them into the CVS and announcing the availability of the document on the Pegasus mailing list with a definition of the review period defined and the date for steering committee review and vote

Project approval is done through community review and the approval of the Pegasus steering committee. The approval of the steering committee is the final authority on the disposition of all PEPs. A review schedule will be maintained for PEPs in the approval process and a means for communicating comments.

The second phase of a project is implementation. The proposer is responsible for the implementation, either doing it himself/herself or arranging for someone else to do it. The implementation may be done either as part of the trunk CVS or separately depending on the characteristics of the change and the possible impact on other components of the prjoect

The third phase of a project is integrating the results back into the official Pegasus CVS release.  This is a two step process, 1) integrating the change back into the repository, 2) validating the change on ALL maintained Pegasus platforms.

For Pegasus approved developers with direct write access to the Pegasus CVS repository this is done by submitting the changes to CVS and documenting the commit with a commit message to the CVS COMMIT Mailing list.  This commit message must include:

1. The PEP number.

2. The Modules Changed.

3. Definition of the testing performed.  At the least ALL changes must be completely tested on one platform before they are submitted to CVS. Completely testing is defined as executing the complete test suite defined in the Pegasus Test Suite defined through the PEGASUSCOMPLETETEST option of the top level Pegasus make file.  Please do not submit changes to CVS until they have been through this set of changes.

We understand that not all developers have access to all Pegasus platfroms. Therefore, there is a second step to the integration process, testing by the platform maintainers.  Part of the role of being a Pegasus platform maintainer will be to regularly test Pegasus using the PEGASUSCOMPLETETEST and to submit the results of those tests to the Pegasus test results maintainer so that an up-to-date state of the operational status of the Pegasus platform can be maintained.

PEP Status

The status field in the PEP document defines the current status of a PEP.  This field will be maintained by the PEP editor as the status changes.  The defined status today are:

  1. Draft - Document in draft but not yet submitted to the community or steering committee.
  2. Active - Documented in the process of review and approval
  3. Accepted - Project accepted by the steering committee
  4. Deferred - Project deferred for future review by the steering committee
  5. Final - Approved project. At this point, the PEP should include not only the definition of the project but planning information such as dates for completion and an indication which version of Pegasus it will be integrated into.
  6. Rejected - Project rejected by the steering committee.  Note that rejected projects may be resubmitted at some future time if the conditions for the project or the objectives of Pegasus were interested in the project.
  7. Withdrawn - Project withdrawn from the approval process. It may be submitted later.

Maintaining Viewing and Commenting on PEP Documents

The PEP is a public document maintained in public space on the Pegasus development web site.

The actual PEP documents will be maintained in the Pegasus CVS project and CVS will be used to provide revision control, distribution and viewing of the documents. The Changes proposals will be maintained in the pegasus/doc/PEP directory.

PEP Format

PEP documents are to be written in HTML with the general format defined below:

PEP Number - This is a number assigned by the PEP editor when the document is first submitted.

Title -  a short descriptive title for the document

Version -  This will be maintained by CVS and displayed in the document using the CVS $Revision: 1.1 $ variable

Author(s) - Names and Email address of authors

Type - Defines the type of the PEP (project, informational, process)

State - Defines the current status of the document. Allowed values are Draft, Active, Accepted, Deferred, Final, Rejected and Withdrawn. This list will be influenced by the finalization of the workflow definition for PEPs.

Vote - The current state of voting for the PEP. Allowed values are Pending, In progress, Done and No voting. The latter is used to indicate a PEP which doesn't require a vote, for example and informational PEP. This information will be provided by the PEP editor.

Documentation References:   Reference to design and other documentation on the project. Note that this documentation will normally not exist when the original documentation is submitted but throughout the life of the proposed change.

Definition of the Project -  This is the meat of any PEP. Project definition PEPs should describe the objectives, and characteristics and schedule of any  feature. The definition of the project should be detailed enough to allow adequate discussion and review of the proposal. The objective is to provide a project management level of information, not the complete design documentation on the project.

Rationale - The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work.  The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.

Discussion - Additional information from discussions, decisions of the steering committee, etc. can be recorded here.

Please use the PEPOutline.htm document defined in the Pegasus PEP archive as the template for all PEP documents.  This will help with the automation of indexing, status changes, etc. as the process develops.

NOTE: There is a single document maintained in the Pegasus CVS (pegasus/doc/PEPS/PEPOutline.htm) that is a template for PEPs to make preparation easier.

Documentation References

A number of other open source projects including Apache, TCL, Python have adopted similar documentation schemes and these were used as part of the basis for this definition.

See: