REP: 1 Title: REP Purpose and Guidelines Author: Ken Conley Status: Active Type: Process Content-Type: text/x-rst Created: 18-Sep-2010 Post-History: 19-Sep-2010, 20-Feb-2012
REP stands for ROS Enhancement Proposal. A REP is a design document providing information to the ROS community, or describing a new feature for ROS or its processes or environment. The REP should provide a concise technical specification of the feature and a rationale for the feature.
We intend REPs 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 ROS. The REP author is responsible for building consensus within the community and documenting dissenting opinions.
Because the REPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [1].
The REP process is based on the Python PEP process. We are thankful to the Python PEP contributors for providing a process, tools, and templates for community participation in a design process.
This initial document is based on a search-and-replace of PEP 1 by Barry Warsaw, Jeremy Hylton, David Goodger. Over time, it will incorporate ROS-specific changes to this process. The Author field of this document has been changed in order to denote reponsibility for maintenance, not credit for original authorship.
There are three kinds of REP:
- A Standards Track REP describes a new feature or implementation for ROS.
- An Informational REP describes a ROS design issue, or provides general guidelines or information to the ROS community, but does not propose a new feature. Informational REPs do not necessarily represent a ROS community consensus or recommendation, so users and implementors are free to ignore Informational REPs or follow their advice.
- A Process REP describes a process surrounding ROS, or proposes a change to (or an event in) a process. Process REPs are like Standards Track REPs but apply to areas other than the ROS language itself. They may propose an implementation, but not to ROS's codebase; they often require community consensus; unlike Informational REPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in ROS development. Any meta-REP is also considered a Process REP.
The REP editors assign REP numbers and change their status. Please post all REP-related email to the General section of discourse.ros.org. Also see REP Editor Responsibilities & Workflow below.
The REP process begins with a new idea for ROS. It is highly recommended that a single REP contain a single key proposal or new idea. Small enhancements or patches often don't need a REP and can be injected into the ROS development work flow with a patch submission to the REP issue tracker. The more focussed the REP, the more successful it tends to be. The REP editor reserves the right to reject REP proposals if they appear too unfocussed or too broad. If in doubt, split your REP into several well-focussed ones.
Each REP must have a champion -- someone who writes the REP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The REP champion (a.k.a. Author) should first attempt to ascertain whether the idea is REP-able. Posting to discourse.ros.org is the best way to go about this.
Vetting an idea publicly before going as far as writing a REP is meant to save the potential author time. Many ideas have been brought forward for changing ROS that have been rejected for various reasons. Asking the ROS community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Just because an idea sounds good to the author does not mean it will work for most people in most areas where ROS is used.
Once the champion has asked the ROS community as to whether an idea has any chance of acceptance, a draft REP should be posted to discourse.ros.org. This gives the author a chance to flesh out the draft REP to make properly formatted, of high quality, and to address initial concerns about the proposal.
Following an initial discussion on Discourse, the draft REP should be posted to Discourse as well. The draft must be written in REP style as described below, else it will be sent back without further regard until proper formatting rules are followed.
If the REP editor approves, he will assign the REP a number, label it as Standards Track, Informational, or Process, give it status "Draft", and create and check-in the initial draft of the REP. The REP editor will not unreasonably deny a REP. Reasons for denying REP status include duplication of effort, being technically unsound, not providing proper motivation or addressing backwards compatibility, or not in keeping with the ROS philosophy. The MDFN (Malevolent Dictator for Now, TBD) can be consulted during the approval phase, and is the final arbiter of the draft's REP-ability.
As updates are necessary, the REP author can check in new versions if they have GIT commit permissions, or can email new REP versions to the REP editor for committing.
Standards Track REPs consist of two parts, a design document and a reference implementation. The REP should be reviewed and accepted before a reference implementation is begun, unless a reference implementation will aid people in studying the REP. Standards Track REPs must include an implementation -- in the form of code, a patch, or a URL to same -- before it can be considered Final.
REP authors are responsible for collecting community feedback on a REP before submitting it for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. Strategies to keep the discussions efficient include: setting up a separate SIG mailing list for the topic, having the REP author accept private comments in the early design phases, setting up a wiki page, etc. REP authors should use their discretion here.
Once the authors have completed a REP, they must inform the REP editor that it is ready for review. REPs are reviewed by the MDFN and his chosen consultants, who may accept or reject a REP or send it back to the author(s) for revision. For a REP that is pre-determined to be acceptable (e.g., it is an obvious win as-is and/or its implementation has already been checked in) the MDFN may also initiate a REP review, first notifying the REP author(s) and giving them a chance to make revisions.
For a REP to be accepted it must meet certain minimum criteria. It must be a clear and complete description of the proposed enhancement. The enhancement must represent a net improvement. The proposed implementation, if applicable, must be solid and must not complicate existing libraries unduly. Finally, a proposed enhancement must be "ROSonic". (However, "ROSonic" is an imprecise term; it may be defined as whatever is acceptable to ROS Developers. This logic is intentionally circular.)
Once a REP has been accepted, the reference implementation must be completed. When the reference implementation is complete and accepted by the MDFN, the status will be changed to "Final".
A REP can also be assigned status "Deferred". The REP author or editor can assign the REP this status when no progress is being made on the REP. Once a REP is deferred, the REP editor can re-assign it to draft status.
A REP can also be "Rejected". Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact.
REPs can also be replaced by a different REP, rendering the original obsolete. This is intended for Informational REPs, where version 2 of an API can replace version 1.
The possible paths of the status of REPs are as follows:
Some Informational and Process REPs may also have a status of "Active" if they are never meant to be completed. E.g. REP 1 (this REP).
Each REP should have the following parts:
Preamble -- RFC 822 style headers containing meta-data about the REP, including the REP number, a short descriptive title (limited to a maximum of 44 characters), the names, and optionally the contact info for each author, etc.
Abstract -- a short (~200 word) description of the technical issue being addressed.
Copyright/public domain -- Each REP must either be explicitly labelled as placed in the public domain (see this REP as an example) or licensed under the Open Publication License.
Specification -- The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current ROS client libraries, if applicable (roscpp, rospy, roslisp, etc...).
Motivation -- The motivation is critical for REPs that want to change the ROS APIs. It should clearly explain why the existing API specification is inadequate to address the problem that the REP solves. REP submissions without sufficient motivation may be rejected outright.
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, e.g. how the feature is supported in other languages.
The rationale should provide evidence of consensus within the community and discuss important objections or concerns raised during discussion.
Backwards Compatibility -- All REPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The REP must explain how the author proposes to deal with these incompatibilities. REP submissions without a sufficient backwards compatibility treatise may be rejected outright.
Reference Implementation -- The reference implementation must be completed before any REP is given status "Final", but it need not be completed before the REP is accepted. It is better to finish the specification and rationale first and reach consensus on it before writing code.
The final implementation must include test code and documentation.
All REP are expected to be formatted in reStructuredText with UTF-8-encoding. reStructuredText REPs allow for rich markup that is still quite easy to read. REP 12 contains instructions and a template [2] for reStructuredText.
There is a Python script that converts REPs to HTML for viewing on the web. reStructuredText REPs are parsed and converted by Docutils code called from the script.
Each REP must begin with an RFC 822 style header preamble. The headers must appear in the following order. Headers marked with "*" are optional and are described below. All other headers are required.
REP: <rep number>
Title: <rep title>
Version: <svn version string>
Last-Modified: <svn date string>
Author: <list of authors' real names and optionally, email addrs>
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Replaced>
Type: <Standards Track | Informational | Process>
* Content-Type: <text/plain | text/x-rst>
* Requires: <rep numbers>
Created: <date created on, in dd-mmm-yyyy format>
* ROS-Version: <version number>
Post-History: <dates of postings to discourse.ros.org>
* Replaces: <rep number>
* Replaced-By: <rep number>
* Resolution: <url>
The Author header lists the names, and optionally the email addresses of all the authors/owners of the REP. The format of the Author header value must be
Random J. User <address@dom.ain>
if the email address is included, and just
Random J. User
if the address is not given. For historical reasons the format "address@dom.ain (Random J. User)" may appear in a REP, however new REPs must use the mandated format above, and it is acceptable to change to this format when REPs are updated.
If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions. Note that personal email addresses in REPs will be obscured as a defense against spam harvesters.
Note: The Resolution header is required for Standards Track REPs only. It contains a URL that should point to an email message or other web resource where the pronouncement about the REP is made.
While a REP is in private discussions (usually during the initial Draft phase), a Discussions-To header will indicate the mailing list or URL where the REP is being discussed. No Discussions-To header is necessary if the REP is being discussed privately with the author. Note that email addresses in the Discussions-To header will not be obscured.
The Type header specifies the type of REP: Standards Track, Informational, or Process.
The format of a REP is specified with a Content-Type header. The only supported values is "text/x-rst", which designates reStructuredText encoding (see REP 12 [2]).
The Created header records the date that the REP was assigned a number, while Post-History is used to record the dates of when new versions of the REP are posted to https://discourse.ros.org. Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2010.
Standards Track REPs must have a ROS-Version header which indicates the version/distribution of ROS that the feature will be released with. Informational and Process REPs do not need a ROS-Version header.
REPs may have a Requires header, indicating the REP numbers that this REP depends on.
REPs may also have a Replaced-By header indicating that a REP has been rendered obsolete by a later document; the value is the number of the REP that replaces the current document. The newer REP must have a Replaces header containing the number of the REP that it rendered obsolete.
REPs may include auxiliary files such as diagrams. Such files must be
named rep-XXXX-Y.ext, where "XXXX" is the REP number, "Y" is a
serial number (starting at 1), and "ext" is replaced by the actual
file extension (e.g. "png").
How you report a bug, or submit a REP update depends on several factors, such as the maturity of the REP, the preferences of the REP author, and the nature of your comments. For the early draft stages of the REP, it's probably best to send your comments and changes directly to the REP author. For more mature, or finished REPs you may want to submit corrections to the REP issue tracker so that your changes don't get lost. If the REP author is a ROS developer, assign the bug/patch to him, otherwise assign it to the REP editor.
When in doubt about where to send your changes, please check first with the REP author and/or REP editor.
REP authors who are also ROS committers can update the REPs themselves by using "git commit/push" to commit their changes.
It occasionally becomes necessary to transfer ownership of REPs to a new champion. In general, we'd like to retain the original author as a co-author of the transferred REP, but that's 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 REP process, or has fallen off the face of the 'net (i.e. is unreachable or not responding to email). A bad reason to transfer ownership is because you don't agree with the direction of the REP. We try to build consensus around a REP, but if that's not possible, you can always submit a competing REP.
If you are interested in assuming ownership of a REP, send a message asking to take over, addressed to both the original author and ros-users. If the original author doesn't respond to email in a timely manner, the REP editor will make a unilateral decision (it's not like such decisions can't be reversed :).
All REP-related correspondence should be sent (or CC'd) to <ros-users@lists.ros.org>.
For each new REP that comes in an editor does the following:
- Read the REP to check if it is ready: sound and complete. The ideas must make technical sense, even if they don't seem likely to be accepted.
- The title should accurately describe the content.
- Edit the REP for language (spelling, grammar, sentence structure, etc.), markup (for reST REPs), code style (examples should match REP 8 & 7).
If the REP isn't ready, the editor will send it back to the author for revision, with specific instructions.
Once the REP is ready for the repository, the REP editor will:
Assign a REP number (almost always just the next available number, but sometimes it's a special/joke number, like 666 or 3141).
List the REP in REP 0 (in two places: the categorized list, and the numeric list).
Add the REP to GIT.
The command to check out a read-only copy of the repository is:
git clone https://github.com/ros-infrastructure/rep.git
Send email back to the REP author with next steps (post to ros-users).
Updates to existing REPs also come in to ros-users@lists.ros.org. Many REP authors are not GIT committers yet, so we do the commits for them.
Many REPs are written and maintained by developers with write access to the ROS codebase. The REP editors monitor the rep-commits list for REP changes, and correct any structure, grammar, spelling, or markup mistakes we see.
The editors don't pass judgement on REPs. We merely do the administrative & editorial part. Except for times like this, there's relatively low volume.
Resources:
| [1] | This historical record is available by the normal GIT commands for retrieving older revisions. For those without direct access to the GIT tree, you can browse the current and past REP revisions here: https://github.com/ros-infrastructure/rep/commits/master |
| [2] | (1, 2) REP 12, Sample reStructuredText REP Template (https://ros.org/reps/rep-0012.html) |
This document has been placed in the public domain.