PEP

PEGASUS Enhancement Proposal (PEP)

PEP #: 001

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

Version: 2.71

Authors: Karl Schopmeyer, Mike Day, Denise Eckstein, Ed Boden

State: Approved

Approvals Required: Steering Committee and Architecture Team

Created: 27 July 2002

Version History:

Version	Date	Author	Change Description
1.0	27 July 2002	K. Schopmeyer	Initial Submission
1.1	7 August 2002	K. Schopmeyer	Clean Up comments from Initial Steerign Committee discussions
1.2	21 March 2003	K. Schopmeyer	Incorporate comments from review (see review comments in earlier version) in Nov 2003 Add more material on types of PEPs, relation between PEP types, submission, and format of documents.
1.3	1 April 2003	K. Schopmeyer	Simplify to define only the change process. PEPs will be used for change management, not for documentation. This is per agreement of Architecture team, 28 March 2003
1.4	6 April 2003	K. Schopmeyer	Remove reference to PEP types and clean up typos. Add comment about copyright notice
1.5	8 April 2003	K. Schopmeyer	Move to full copyright/license in the text of each document Correct typos from Ballot
1.6	11 April 2003	K. Schopmeyer	Remove PEP format details from this document to the PEP format document PEP 000.
1.7	28 April 2003	K. Schopmeyer	Incorporate comments from approved version 1.6. This is version released.
2.0	22 Jan 2004	Ed Boden	Basic refresh, align with practice, PEP categories
2.1	23 Jan 2004	Ed Boden	More specifics about this 2.* version are added. Basic refresh; pep number format changed in PEP and in format section, latest copyright, added schedule, added rationale, added discussion, fix typos. Align with current practice; PEPs are used for more that just code changes to Pegasus so language broadened in abstract & introduction, added PEP categories section with existing 3 categories and proposed 2 more, added section on balloting, added key 'rules' concerning CVS commits. Added brief summary concerning of discussion about PEP and test code. Added color coded substantive changes.
2.2	03 Feb 2004	Ed Boden	The following changes were made per 2.1 comments and 2/3 Arch team discusion; Wording of abstract. Wording of 1st paragraph. Added table for PEP categories. Added list of suggested subcategories for Functional PEPs. Changed words in balloting section. Added missing ')'. Corrected Veritas copyright.
2.3	06Feb 2004	Ed Boden	Changes, from comments and today's arch team discussion, are; 1) remove all previous color coding of text 2) description and table for Concept PEPs; now balloted. 3) the category 'Discussion PEP' was added, essentially replacing 'Futures PEP'. Description reworded 4) updated words in PEP LifeCycle section to show new terminology for the 2 PEP section on the web page and how we want to use them 5) small changes in PEP Status section 6) updated the schedule section 7) color coded the changed text
2.4	13 Feb 2004	Ed Boden	Changes, from comments and today's arch team discussion, are; 1) fixed font differences & fixed typos and spelling 2) added CVS caveat to Process PEP description 3) added some additional (Functional) PEP subcategories 4) added some discussion notes
2.5	27 Feb 2004	Ed Boden	Changes per comments and today's arch team discussion, are; 1) consistency in opening para. 2) ')' adjust in 2nd para. 3) elaboration on use of Functional PEP 4) subcategory clarification 5) last sentence under PEP Balloting reworded. 6) comment added on formatting of upload PEP title 7) updated next to last discussion item 8) added 2/27 discussion items
2.6	04 Mar 2004	Ed Boden	Changes per comments and 3/2 arch team discussion, are; 1) basic build & text expectations made more explicit in section on CVS commits. 2) added URL for The Open Group terminology in Documentation section
2.7	12 Mar 2004	Ed Boden	Changes per comments in 2.6 are; 1) rewording of bugzilla reference in 'what is a PEP' section. 2) changed term; PEP 'category' to PEP 'type' everywhere it appears. 3) changed term; 'subcategories' relabeled 'functional categories', so these are easily thought of as applicable to any PEP, rather than just functional PEPs. 4) terminology doc reference converted to hyperlinks, along with a couple of other links
2.7 final	20 Mar 2004	Ed Boden	Finalization edits on 2.7; 1) high-lighting of changed text removed. 2) Added missing word, last sentence of PEP Balloting paragraph. 3) Added recommendation to use an HTML editor. 4) Removed word 'must' from example terminology list.
2.71 final	23 Apr 2004	Martin Kirk	Minor editorial change to replace "Accepted" status with "Approved" as decided by the Steering Committee

Abstract: This document describes the Pegasus Enhancement Proposal (PEP) process. This process is used by the OpenPegasus Community to foster community discussion and receive approval for enhancements to OpenPegasus processes, source and documentation.

What is a PEP?

The Pegasus Enhancement Proposal (PEP) process is the change request mechanism used by the Pegasus Community to organize discussions and control changes to OpenPegasus processes, source and documentation. A PEP is a document used to describe a requested change, enhancement or clarification to OpenPegasus. PEPs are numbered documents maintained on the OpenPegasus web site.

Within OpenPegasus, all process, source and documentation enhancements MUST be approved using the PEP process. Bug fixes, documentation errata and minor enhancements MAY be submitted using the lighter weight process described in PEP 2 (bugzilla process).

The OpenPegasus PEP is a public document maintained in public space on the OpenPegasus development web site. Note that PEPs in the review process are maintained in the "Review Documents" segment of the site (the visibility of documents uploaded to the document review section must be Work Group but that is simply to assure that reviewers log into the site before reviewing the documents so there is an authors name attached to online comments). There is no membership commitment required to The Open Group to submit, review, comment, or use Pegasus PEPs.

PEP types

Different types of PEP are recognized and handled by the OpenPegasus web site. When you submit a PEP to OpenPegasus, you should specify one of these types.

Procedural PEPs -- these describe some aspect of how the OpenPegasus community works; procedures, conventions, etc. This PEP is an example. Generally, this kind of PEP does not drive changes to files in OpenPegasus CVS (versus OpenPegasus CVS; e.g. an exception is a PEP which can change or define CVS tags). Also known as 'process' PEPs.
Functional PEPs -- these describe some proposed changes to OpenPegasus function and are mostly technical (or very implementation specific, with low-level design); in the CIMOM, test clients, sample providers, CLI, even documentation, etc,. The submitter of a functional PEP is also proposing (agreeing, committing) to make the proposed changes. Generally any proposed changes to files kept in OpenPegasus CVS are covered by a functional PEP (with the exception of bug fixes). (Enhancements which are too extensive for an initial commitment should be handled via a Concept PEP which proposes the staging (steps) of implementation. Successive (perhaps very succinct) Functional PEPs would then handle details for each stage (perhaps by different implementers).)
Release PEPs -- these are about a specific OpenPegasus release and provide specific sorts of information for that specific release. For example, each release usually has a 'release content' PEP, 'release notes' PEP, and a 'readme' PEP, and a 'interface' PEP. These PEP always state in their title which OpenPegasus release they are about.
Concept PEPs -- these are technical PEPs that explore or analyze an area of potential improvement. They may merely outline the problem in some technical detail. They may propose a technical direction or an architecture, or staging of function across Pegasus releases. There is no commitment to implementation for these PEPs, (unlike functional PEPs), and they tend to be broader, or much broader. They are never the proximal reason for a change to OpenPegasus CVS files. They are submitted for review and comment, to help move OpenPegasus community discussions forward, and may engender later functional PEPs, by someone. They are balloted as usual and approval indicates that the Architecture team agrees with the facts, analysis or recommendations (if any). Some examples of desirable concept PEPs are; provider SDK, CVS code reorganization, response chunking, Pegasus lite and a test architecture for Pegasus.
Discussion PEPs -- these PEPs are to raise & conduct discussions, using the review capabilities of the web site; make proposals, collect community feedback and provide perspective; all without the necessity of getting actual PEP approval (via ballot). Some at-hand examples are the 'roadmap' PEP (which explores multi-release views of Pegasus), and the 'wish list' PEP in which people put ideas for things they want. There is no commitment to an implementation associated with these PEPs. They are another tool to move discussion ahead, potentially without the overhead of explicit discussion in Architecture team conference calls, and provide more structure than using the OpenPegasus mailing lists. Of course, A Discussion PEP may result in later concept or functional PEPs.

The following table helps clarify these types.

PEP type	what problem is solved by this type of PEP?	can change CVS files?	balloted?	possible status values	means what, if approved?
Procedural	where & how to document OpenPegasus procedures	no	yes	all	some OpenPegasus procedures or processes are agreed-to
Functional	enhancements to Pegasus	yes	yes	all	a change to Pegasus function
Release	collects release-specific information in manageable units	yes	yes	all	some aspect of a specific OpenPegasus release
Concept	a means to document ideas & get feedback about areas of potential enhancement without commitment to implement	no	yes	all	for recommendations for follow-on work, they are balloted. if approved, they are moved to the 'approved documents' section.
Discussion	a means to document ideas, make proposals, etc. & get community feedback	no	no	"draft" "withdrawn"	not applicable; these PEPs remain in the 'review documents' section until archived or withdrawn.

List of suggested functional categories for PEPs

These (or similar) functional categories are suggested as a further means to simplify finding PEPs on the web site. These may be applied to any PEP type, where appropriate. (This is motivated by the growing number of Functional PEPs, which are expected to continue to comprise the majority of OpenPegasus PEPs.)

Pegasus server (includes the repository, provider manager(s), etc.)
Pegasus client (includes the CIM listener, CIMClient, CLI, etc.)
mof compiler
command-line tools (e.g. cimconfig, cimprovider, cimauth, etc.)
provider interface
pervasive Pegasus server (e.g. globalization, auto_ptr, tracing, logging, etc.)
security
standards compliance
test
providers

PEP Lifecycle

The process of submitting an enhancement request to the OpenPegasus Community for review and approval begins with the submission of a PEP to the OpenPegasus WEB Site. Proposals are submitted by uploading the PEP document to the Pegasus PEP page on the OpenPegasus web site (http://www.openpegasus.org) in the "documents for review" section. PEP documents submitted to this page become part of the review/approval process.

NOTE: The OpenPegasus web site includes a function for online review of documents. New documents should be uploaded to the "review documents" section, where they can be reviewed online and comments incorporated directly into the document itself.

The submitter is responsible for numbering new PEPs, marking them with 'Draft' status, submitting them to the PEP review process, and announcing the availability of the document on the Pegasus-devel mailing list (the document submission process has an option to send email upon submission). Note that the author/submitter sets the initial review schedule (start and end date as part of the submission). Normally the start date for review is set to the upload date and the end date for the review to the next meeting of the group at which the document is to be reviewed. Normally, we request that the review period be at least 4 working days so that a document to be reviewed by the steering committee or Architecture team should be uploaded at least 4 working days before the meeting/telecon at which it is to be reviewed and the end date set to the date of the next meeting.

PEP review/approval is accomplished through open community review, the approval of the Pegasus Architecture Team, and the Pegasus steering committee (see voting section). 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. Comments are communicated either by adding them directly in the document being reviewed or by submitting them to the process through email on the pegasus-devel mail alias. Adding them directly to the document is the preferred method since all of the review comments can be seen at the same time and in context.

Once a PEP is approved it is the responsibility of the submitter to upload the document (with any changes defined and agreed-to in the approval process) to the "Approved PEPs" section of the Pegasus PEP page with the status marked "Approved". Note that documents in the "Review Documents" section cannot be moved directly to the "Approved Documents" section of the OpenPegasus web site because documents in the review section have the comment marks inserted into the document as part of the upload process; upload the approved version of your PEP to "Approved Documents". All documents in the "Approved Documents" section of the OpenPegasus web site must have been approved via the Architecture and/or Steering Committee.

PEP Balloting

The Open Group web site's browser-based 'ballot' facility is used by the Architecture team. If 1 or more PEPs are scheduled for ballot, a ballot is posted to the web site prior to a scheduled Architecture team meeting, and people vote online on each PEP in the ballot. A representative from each Steering committee company needs to vote on a given PEP, else the ballot is incomplete and will be held again for that PEP. We'd like to encourage active involvement by the Community in the Architecture team. As a general rule, the Architecture Team attempts to gain consensus on all votes. If a 'no' vote for a PEP cannot be resolved at the Architecture Team level, this issue may be escalated to the Steering Committee for resolution.

PEP Status

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

Draft - PEP is in the process of being reviewed and approved. All PEPs submitted to the PEP review process should be marked as "draft" status.
Approved - PEP approved by the steering committee/Architecture team (via ballot). (Discussion PEPs are never 'approved'.)
Deferred - PEP deferred for future review by the review process or the submitter.
Rejected - PEP rejected by the steering committee or architecture team. Note that rejected PEP may be resubmitted at some future time if proposal is changed to correct reasons for the rejection or the OpenPegasus project becomes interested in the change. Normally the reason for rejection is reflected in the minutes of the meeting where the PEP was rejected and as a comment in the PEP itself. Rejected PEPs will not be moved to the "approved documents" section of the PEP web page. They will remain in the "review documents" section until archived.
Withdrawn - PEP withdrawn from the approval process. It may be submitted later. Normally it is only the submitter who can withdraw a PEP.

PEP Format

PEP documents are to be written in HTML (figure attachments are allowed) with the general format defined below so they may be uploaded to the OpenPegasus WEB site. The format for PEPs is defined in a PEP template that is available from the OpenPegasus WEB site PEP page as PEP 000 - PEP Template: It is recommended that an editor designed to edit HTML is used to edit PEPs, as results typically have fewer formatting problems.

Using this template will simplify use of the required structure for a PEP. The required components are defined in the PEP Template itself.

PEP Numbering: - It is the responsibility of the author to assign this number (see the web site to determine the last number used and to put the next available number into the document and define it in the description part of the upload page). All PEPs should use 3 (decimal!) digit numbers.

NOTE: To make PEP documents easier to manage please name all PEPs as follows and also use the same form in the description so that sorting, etc. on the WEB site can order PEPs by number.

Document Name (Note that the site only accepts HTML documents today)

PEP nnn - Descriptive title

where:

     nnn is the PEP number

        Document upload description (helps with sorting the PEPs into number order)

        PEP#nnn - Descriptive text

            where:

                nnn is the PEP number and there are no spaces in 'PEP#nnn' (because spaces

                mess up the sorting on the web page)

Content of PEPs

Though not all these sections are equally appropriate for all PEP types, generally PEPs contain the following content:

Definition of the Problem - What is this change/enhancement trying to solve.

Definition of the Proposed Solution - This is the meat of any PEP. This section should describe the objectives, and characteristics of the enhancement. 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 and architecture level of information, so that the steering committee and architecture team reviews and approvals can be accomplished.

Rationale - The rationale fleshes out the specification by describing what motivated the proposal and why particular design decisions were made. It should describe alternate designs that were considered and related work.

Schedule - Definition of schedule and implementation plans for PEPs if there is such a plan for this PEP. The more extensive the work, the more a plan with steps defined is needed not just for the review but so others know when definitions and components will be available to support any required integration.

Discussions - Additional information from discussions, decisions of the steering committee, etc. can be recorded here. Note that this is effectively an appendix to the PEP. Normally it is a record of discussions and reviews. The contents of this section are informational only and not considered part of the approved PEP.

NOTE: A PEP may be submitted and reviewed multiple times during the process of defining an enhancement. For example, the initial submission may be simply the problem definition so that this can be discussed and reviewed as in the architecture team. It remains in draft status (with appropriate additions to the Discussion section documenting the reviews, etc.) as subsequent sections of the PEP are documented, submitted, and reviewed. In other words, it need not be the complete solution before it is submitted for review.

All PEPs should include the copyright notice that is defined in the PEP Template (PEP 000).

Basic rules about CVS commits

Regardless of the etiology of any change to any OpenPegasus CVS file, or group of files, the change ...

1) must not break the Pegasus build, and
2) must not break the automated Pegasus test cases.

The OpenPegasus communities' essential expectations with respect to build & test of new (or changed) code are; the changes should work (build and all regression tests pass successfully) on a first platform (linux or windows), and reasonable efforts should be made to ensure that the changes also work on a different second platform (developer's choice). Documentation References

Basic terminology usage ('shall', 'may', etc.) for The Open Group (TOG) can be found at: http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap01.html

Acknowledgement: 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 the following for examples of processes similar to the Pegasus process:

The Apache web site - http://www.apache.org
TCL TIPS site at http://www.tcl.tk/cgi-bin/tct/tip/
Python project management web site at http://www.python.org/peps/

Rationale

Update our base process PEP to align with the way we are working, refresh the document for format and terminology, document the PEP categories, and voting specifics.

Schedule

The goal is to have this PEP approved early in the 2.4 cycle.

action	planned	actual	comment
PEP submitted	01/22/2004	01/22/2004
PEP reviewed	02/06/2004	repeatedly during Jan & Feb 2004	(Refer to version history for more detail on reviews.)
PEP approved	02/20/2004	03/19/2004	2/13/2004 Arch team call: we agree that its ok to begin using the categories. Approved in Ballot 41.
Code committed	n/a	n/a	(This a process PEP; there is no associated code.)

Discussion

Discussion in 1/23 arch call; should submission of test code to OpenPegasus CVS require a PEP? General feeling was no, because we want to make it easy for people submit test code. This has been our practice for some months now. Is a PEP prohibited for test code? On this question, there was less agreement. The next question was; if a PEP is submitted for test code, should we ballot it? If we don't ballot it, how does it get to approved status? Status: in 2/13/2004 Arch team discussion we agree to leave this somewhat open for now, and see if the existing 5 categories are sufficient.

2/13/2004: we also agreed to add to PEP template (PEP#000) a 'category' (pick 1) and 'subcategory' section (pick 0 or more). Confirmed in 2/27/2004 comments.

2/27/2004: a) Over time, we'd like the TOG web infrastructure support for PEPs to handle the PEP categories and subcategories as attributes, contained within the document itself, and read by the web site automation for display on web pages, sorting, value enforcement, subheadings, etc. This applies to other PEP attributes such as PEP numbers which preferably would be automatically generated and controlled by the web site infrastructure software.

b) Another type of PEP has been mentioned: Documentation PEP. Until the categories of (for example) Test & Documentation PEP are formally defined, it is appropriate that some combination Concept and Function PEPs be used. Admittedly, 'functional' may not be the best label in these cases, but test & documentation can be regarded as special cases of this category because files in OpenPegasus CVS will be updated, when documentation or test enhancements are made.

Copyright (c) 2004 EMC Corporation; Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.