[ANSI-Smalltalk] Process proposal

[Paolo Bonzini]

Hi all,

I have written a draft of how our own open process might work.  It is 
called STEP and, as the name may suggest, it is roughly based on the 
Python process (PEP).  I mailed it to Bruce privately and he suggested 
to make it public.

The main changes from PEP are the following:

1) the concepts of a reference implementation, expert group and 
maintenance are inspired from JCP (of course the RI is different due to 
Smalltalk-specific issues);

2) the editors are fixed in PEP, while I made them a voluntary position;

3) the states are a little different (with some inspiration from 
Bugzilla...), both to reflect the voluntary nature of being a STEP 
editor, and in some cases because I thought this way is better;

4) the process includes the forwarding of the open specification to the 
ANSI committee;

5) some parts (notably "Successful discussion of a STEP") are mutuated 
from Wikipedia policies and essays instead.

If there is consensus for at least the basic structure of the proposal, 
I will put it on the GNU Smalltalk wiki so that it can be edited by 
anyone.  The STEPs themselves could be hosted there (there are some 
modules, in the CMS I am using, that would help the management).

Citing the document itself, "we try to build consensus around a STEP, 
but if that is not possible, you can always submit a competing STEP."

Cheers,

Paolo
-------------- next part --------------
== 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.

== STEP lifetime ==

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:

* 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 (~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
once somebody 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:

    # circo < step.dot |dotty -
    digraph G {
      "Draft" -> "Under discussion";
      "Draft" -> "Rejected";
      "Draft" -> "Withdrawn";
      "Draft" -> "Suspended";
      "Under discussion" -> "Suspended";
      "Under discussion" -> "Accepted";
      "Under discussion" -> "Rejected";
      "Under discussion" -> "Withdrawn";
      "Suspended" -> "Draft";
      "Suspended" -> "Rejected";
      "Suspended" -> "Withdrawn";
      "Accepted" -> "Standard track";
    }

All STEPS are licensed under the same license [I wrote CC-BY in an earlier
draft but I don't know if it's compatible with the ANSI standardization
process---in which case we might decree that all PEPs are in the public
domain].

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.

In addition, we request the reference implementation to possess several
properties:

* it must prove 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.