ooc-dev team mailing list archive

[Tres Walsh <tres.walsh@xxxxxxxxx>]

Hello!

I was talking with nddrylliog in the IRC Channel about emulating the
Python Enhancement Proposal, for suggesting new features to the
language. After a bit of thinking, I came up with the acronym you see
above. As such I'd like this actual message to be the "first" ORC,
laying out a general guideline, which can be tweaked and added to by
other members of the community (before our BDFL signs off on this of
course :D ). So below this very brief header you will find my attempt
to create an ORC guideline/writing style, as well as try to explain
their purpose. (I'm effectively modifying PEP 1, I should mention,
however I'm removing parts that I deem unnecessary. Please remember,
anyone can modify this, and I'd prefer the community approve of it
first :D). Also, I should briefly mention that I'm using markdown
syntax, as it comes off a bit easier to read in email format compared
to say rst. And please. I appreciate any and all feedback.


Author:   Tres Walsh (SAHChandler)
Created:  March 29th, 2010
Type:     Guideline
Status:   Draft

ORC Purpose and Guidelines
==========================

   + What is an ORC?
   + ORC Types
   + ORC Workflow
   + Writing an ORC
   + Transferring ORC Ownership
   + References and Footnotes


What is an ORC?
---------------


ORC stands for ooc Revision Consideration. An ORC is a design document
providing information to the ooc community, or describing a new
feature for ooc or its processes or environment. The ORC should
provide a concise technical specification of the feature and a
rationale for the feature.

We (the ooc community) intend ORCs to be the primary mechanisms for
proposing new features, for collecting community input on an issue,
and for documenting the design decisions that have gone into ORC, as
well as the invasion of Middle Earth. The ORC author is responsible
for building consensus within the community and documenting dissenting
opinions.

ORCs should be stored in a versioned repository (preferably git), so
that any new members to the ooc community may see the history of ORCs.


ORC Types
---------

There are several types of ORCs

   1. Guideline - A guideline dictates a way in which ooc workflow is
to be performed, from code generation, to compiler implementation, as
well as any other role that would require a rule of some sort.
   2. Feature   - A core language feature. Accepted Feature ORCs will
become part of the ooc standard library. Feature ORCs that do no
propose a true cross platform implementation, or feature, should be
named as Extension ORCs instead.
   3. Extension - An extension is any additional library. This could
be anything from a language bridge (e.g. ooc to Python), to a platform
specific feature (e.g. DirectX or Cocoa bindings). As these are not
part of the core ooc language, they are not required to be implemented
by implementations other than the core ooc implementation (i.e. rock).
   4. Fix       - If the community as a whole sees a problem with the
language, one that would take considerable time to fix, a Fix ORC
should be used. This could detail a new memory model, or writing a
garbage collector in ooc, something that would affect the core
language, but isn't a feature, as the proposal is a fix to a pre
existing feature. If a feature currently exists, but there is no
guideline, feature, or extension for it, Fix ORCs should not be used.


ORC Workflow
------------

An ORC may have only one idea, or a single solution to any given problem.

Each ORC must have a champion. This is the person who writes, hypes,
and answers any and all questions related to the ORC throughout its
lifetime. This person is also known as the Author. Before writing the
ORC, the Author should ascertain if there is any interest in such an
ORC by asking the community in the mailing list, or the IRC Channel.
Of course, if most feedback is negative, the Author should seriously
consider *not* writing the ORC, though there is nothing stopping them.

Once the ORC has had what appears to be a decent amount of positive
feedback, a draft ORC should be submitted to the community. This
allows the Author to modify the ORC more to the community's wishes, as
well as fix any problems before the ORC is submitted.

Finally the ORC is submitted to the BDFL (Benevolent Dictator For
Life) for final review. The BDFL may or may not choose any members
from the community to discuss the ORC with.

If the ORC is approved, it will be placed in an as of yet undetermined
repository for public consumption and will be a part of the official
language specification.

If an ORC is rejected, the BDFL, and any consultants must inform the
community of their decision, as well as the reasoning behind. The ORC
will then be marked as rejected, and placed in a separate part of the
ORC repository, as a record of it's existence, and to ensure that
multiple ORCs on the same subject or idea are not proposed.

After 1 year, the Author of a rejected ORC may make a case to move
their ORC from rejected to accepted. At this point the ORC will be
placed in draft status, and the community will once again be allowed
to voice their opinions. There is no limit as to how many times an ORC
may be tasked for re-evaluation.

An ORC can replace, or make a previous ORC obsolete. In this instance
the older ORC will be marked as Obsolete.


Writing an ORC
--------------

An ORC must have the following layout


Header:

The Header must contain the Author's name, as well as any alias they
use in the ooc community (This is for recognition in the IRC Channel).
It must also contain the date the ORC was written. There is currently
no set in stone Date format, though this is expected to change with
this draft's first revision. The Header must also contain the ORC's
name as well as its current status (Draft, Under Review, Accepted,
Rejected, Obsolete, Withdrawn)

License:

All ORCs are released in the public domain, and as such are not
required to state any license agreement.

Index:

A Bulleted List containing the names of subsections are placed in the
ORC, under a large header of the ORC's name.

Motivation:

A small paragraph explaining the reasoning behind the ORC proposal.

Specification:

A detailed analysis of the *how* of the ORC, explaining it's
implementation, and possible problems that may arise from it.

Rationale:

A detailed analysis of the *why* behind the ORC, explaining it's
necessity to the community.

Issues:

Any issues that may arise be it from platform implementations, to
compiler issues, as well as any problems the Author may have with the
ORC.

References and Footnotes:

The end of the ORC should contain links to any references mentioned in
the ORC, as well as footnotes, such as explanations for terminology
used.


Transferring ORC Ownership
--------------------------

Every so often the transfership of an ORC's owner is necessary.
Whether this be from the Author's disappearance in Real Life, to
death, to general dislike of working with the ORC. In the two former
cases, a member of the community must contact the BDFL and inform
them. If no one steps up, the BDFL will automatically take ownership
of the ORC, but may delegate to any member in the community who has
shown a willingness in helping with the ORC. The BDFL may also mention
to the community a lack of interest, and a need for a new Author. In
the last case however, the Author must mention their unwillingness to
continue to work on the ORC, and request a member of the community
step up. Once a member has come forward, the BDFL must be contacted,
and informed of the switch. The BDFL's permission is not required as
it may overwhelm the BDFL.


References and Footnotes
------------------------

None