PEGASUS Enhancement Proposal (PEP)
PEP #: 1
TITLE: Pegasus Project Enhancement Proposals - Guidelines and the Approval Process
Version: $Revision: 1.2 $
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.
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.
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.
We envision three types of documents:
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.
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:
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 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.2 $ 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.
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: