Diff for The STEP specification and workflow

Tue, 02/19/2008 - 11:09 by Paolo BonziniMon, 08/29/2011 - 08:43 by Paolo Bonzini
Changes to Body
Line 19 Line 19
== The life of a STEP == == The life of a STEP ==
-A STEP officially starts its life when a first draft is published. Even in its first revision, a STEP should already include the following metadata: +A STEP officially starts its life when a first draft is published (using the "[http://smalltalk.gnu.org/node/add/book/parent/173 Add child page]" link on the STEP main page) and announced on the [mailto:ansi-smalltalk@lists.openskills.org STEP mailing list].
 +
 +Even in its first revision, a STEP should already include the following metadata:
* the author, i.e. the person who took care of the initial writing of the STEP, who will champion it to the community, and who will take care of updating the STEP as discussion takes place; * the author, i.e. the person who took care of the initial writing of the STEP, who will champion it to the community, and who will take care of updating the STEP as discussion takes place;

Current revision:

The STEP specification and workflow

Abstract

We present the structure for STEPs (Smalltalk Enhancement Proposal), design documents providing information about the Smalltalk language, library or environment, or describing a new feature. STEPs are meant to drive discussion of features in the Smalltalk community, and are intended to be the primary mechanisms for proposing new features to the community as well as to a standards body.

This document specifies the structure and workflow of a STEP, and documents the properties that will make sure that a STEP is easily implementable on a wide range of dialects.

Introduction

STEP stands for Smalltalk Enhancement Proposal. A STEP is a design document providing information about the Smalltalk language, library or environment, or describing a new feature. The STEP is meant to be an initial point for discussion in the Smalltalk community, and at the same time should be reasonably developed at the time it is made public, so as to provide rationale for the feature and for debatable details.

We intend STEPs to be the primary mechanisms for proposing new features to the community as well as to a standards body, which may base its decisions on STEPs after the community has given its input on the issue and reached consensus. The finalized STEP will document dissenting opinions adequately, so as to preserve the rationale for design decisions after they have entered the Smalltalk standard.

Ideally, each STEP would represent a new idea for Smalltalk---therefore, the ideal STEP would be focused on a single key proposal. It is expected that the community will not focus its attention to STEPs that appear too broad.

Bugfixes in general do not need a STEP and are better submitted to a particular dialect's issue tracking system. However, ascertained bugs in the ANSI specification, requests for harmonization of a feature across different dialects, and similar issues can be discussed via a STEP.

Special-purpose STEPs (referred from now on as "meta-STEPs") can also propose procedures, guidelines, or changes to the decision-making process surrounding STEPs themselves.

The life of a STEP

A STEP officially starts its life when a first draft is published (using the "Add child page" link on the STEP main page) and announced on the STEP mailing list.

Even in its first revision, a STEP should already include the following metadata:

  • the author, i.e. the person who took care of the initial writing of the STEP, who will champion it to the community, and who will take care of updating the STEP as discussion takes place;
  • a list of possible experts, i.e. people who are active practitioners in the technology covered by the STEP, or who are actively working on a reference implementation of the technology;
  • a list of prerequisite STEPs, upon whose contents discussion will be implicitly based;
  • a list of STEPs that this proposal, if accepted, would supersede;
  • a list of preexisting documents (other than STEPs), technology descriptions, or implementations that might be used as a starting point;
  • a license under which the reference implementation, if any, would be released;
  • optionally, the indication of an appointed editor of the STEP, whose duties are described later in this document;
  • an abstract: a short (100-200 word) description of the technical issue being addressed.

Discussion on the STEP starts immediately; however, if no editor is mentioned in the STEP, it formally enters "Under discussion" state only after someone steps up as the editor of the STEP. The editor's duty is to follow the discussion and ascertain when consensus on acceptance or rejection of the proposal is reached. Since the editor acts as an impartial referee on the progress of the STEP, it is suggested that the editor is *not* chosen among people already familiar with the STEP.

If no editor steps up within one month of the presentation of the STEP, the STEP moves to the "Suspended" state. If no editor steps up within two months, the community is understood to declare lack of interest for the STEP and the proposal is "Rejected". The author is responsible for following these phases while there is no appointed editor.

Once the editor is appointed, any change in the STEP state is made by the editor. Therefore, the editor also has the duty of keeping in contact with the author to understand whether progress has been made on the comments raised by the community, and suspending/withdrawing the STEP if this is not the case after a reasonable amount of time.

Finally, after the STEP has been accepted, the editor may propose that it enters an official standardization process. This is the only step that requires a formal voting process. The exact details for the voting process, including the quorum, shall be decided during discussion of this proposal, or otherwise left for a future meta-STEP.

The following diagram summarizes the life of a STEP:


All STEPS are licensed under the same license [to be defined].

STEPs are maintained in a versioned repository, and their revision history is the historical record of the feature proposal.

Exceptional events

It occasionally becomes necessary to transfer the role of author or editor of a STEP to a different person. In general, we would like to retain the original author as a co-author of the transferred STEP, but that is really up to the original author. A good reason to transfer ownership is because the original author no longer has the time or interest in updating it or following through with the STEP process, or is unreachable or not responding to email. A bad reason to transfer ownership is because you do not agree with the direction of the STEP. We try to build consensus around a STEP, but if that is not possible, you can always submit a competing STEP.

If you are interested in assuming ownership of a suspended STEP, send a message asking to take over, addressed to both the original author and the editor. If the original author will not respond to email in a reasonably timely manner, the editor may make a unilateral decision.

Maintenance

While discussion is supposed to take place before a proposal is accepted, the STEP remains a living document even after this milestone is reached.

In particular, it is important that the completed specification, reference implementation, and technology compatibility kit are updated in response to ongoing requests for clarification, interpretation, enhancements, and revisions. The author should review all proposed changes to the specification and indicate which ones can be carried out immediately and which should require the specification to be revised with a new STEP.

Challenges to one or more tests in a specification's technology compatibility kit are ultimately decided by the author if they cannot be otherwise resolved.

It is suggested to keep track of frequently raised issues and make the resolutions available from within the STEP itself. In addition, whenever the specification is updated, the author is responsible for reviewing the reference implementation and technology compatibility kit to determine what revisions (if any) are needed to keep them synchronized with the updated STEP.

Maintenance is especially important for STEPs that are going to enter the ANSI process. If the author is not part of the ANSI committee, it is probably best to relinquish the lead of the maintenance process to a member of the committee (possibly an expert identified in the STEP itself).

The road to a successful STEP

Even if the number of people involved in the STEP process will be relatively small, it is expected that in some cases the stakes will be important enough that there will inevitably be disagreement. Therefore, it is useful that the STEP guidelines describe not only the formal steps leading to acceptance of a proposal, but also summarize the contents of a successful proposal and the basic steps towards effective decision making.

This section should not be interpreted only as a strict policy; while it does include some normative content, it mostly consists of advice that will help minimizing these problems. Similar essays, representing the advice and opinion of their author, may be presented as meta-STEPs in the future.

What belongs in a successful STEP?

While not all STEPs may need all these parts, including the following information can be a good start towards community acceptance of a STEP, and towards fruitful discussion of a STEP even in its infancy:

  • a motivation, which should clearly explain why the existing language specification is incomplete, or inadequate to address the problem that the STEP solves. The motivation is critical for STEPs that include backwards-incompatible changes---without sufficient motivation, such submissions can be expected to be rejected outright.
  • a technical specification, describing the syntax and semantics of any new feature, detailed enough to allow competing, interoperable implementations for as many Smalltalk implementations as possible.
  • a rationale which 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, e.g. how the feature is supported in other languages or in existing implementations other than the STEP reference implementation. The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
  • a section describing backwards-incompatible changes introduced by the STEP (if any), and discussing their severity. Submissions without a complete discussion of backwards compatibility may be rejected outright, or may fail to enter the standards track.
  • when applicable, a reference implementation, to be completed before any STEP is accepted, but which needs not be completed at the time the STEP's discussion begins. It is better to finish the specification and rationale first and reach consensus on it before writing code for possibly controversial aspects of the spec.

We request the reference implementation to fulfill several requirements:

  • it must prove that the specification can be implemented fully;
  • it must include a technology compatibility kit (a suite of tests, tools, and/or documentation that is used to test implementations for compliance with the specification), available under an OSI-approved license;
  • when applicable, the technology compatibility kit must provide 100% coverage of the globals, protocols, selectors and error conditions in the specification.

In addition, the following properties are desirable:

  • the reference implementation should run on at least two implementations of Smalltalk;
  • the reference implementation should run on at least one open-source implementation of Smalltalk;
  • the technology compatibility kit should be available under a GPL-compatible license;
  • a reference implementation working on at least one implementation of Smalltalk should be itself available under an OSI-approved, GPL-compatible license.

Successful discussion of a STEP

The STEP process will work best if decision are taken by building consensus.

It is expected that consensus will be reached naturally as a product of the discussion process. Furthermore, the relatively narrow focus and the public nature of the STEP process guarantee enough exposure that silence can be interpreted as consent. To guarantee the effectiveness of the process, a limited amount of "bureaucracy" (such as the appointment of the editor) shall provide a safety net against misinterpretation of the community's opinion.

When there are disagreements, they should be resolved through reasoning, cooperation, and if necessary, negotiation. To this end, it is important that members of the community:

  • try to be flexible and understand the other side's reasons;
  • understand that consensus is not immutable and that letting the community change its mind is fundamental for fruitful discussion;
  • do not try to bend the discussion towards their side, for example by asking for help in a completely different "venue" (mailing list, forum, etc.) in the hope of finding more support for a soon-to-be-failed proposal;
  • do not damage the STEP process to support their opinion.

Copyright

This document is hereby placed in the public domain.

User login