Robotics Enhancement Proposal Process and Guidelines

What is a REP?

REP stands for Robotics Enhancement Proposal. A REP is a document providing information for anyone interacting with one or more of the OSRA’s open-source projects in a user- or developer-like way. It provides the what, how, and (most importantly) why, of any enhancement to one or more OSRA projects.

The REP process is not intended to replace Pull Requests (PRs) and the existing PR process, but to work with and enhance these. This is particularly true for very large changes that may require multiple PRs or cover multiple repositories or even projects.

REP Audience

The broad target audience for REPs are people who are using OSRF software to develop robots, systems using robots, and tools for robotics. The specific audience, however, varies considerably by REP. This is because each REP may target a different subset of the OSRF’s projects, and a REP may provide either some kind of standard (such as coordinate frame structure and naming), or provide some kind of specification (such as a data format for point cloud data when transmitted across the wire).

Additionally, the audience for a REP may be broader if that REP is being used to coordinate some work across multiple projects.

REP Types

A REP should be created for the following types of changes/proposals.

1. Standard - These documents lay out a set of constraints or patterns that projects belonging to some category are expected to comply with. This covers topics including but not limited to: standard units of measure, coordinate frame patterns, package naming patterns, and interfaces for specific hardware drivers.
2. Specification - These documents unambiguously specify some information format that downstream consumers must implement. Examples include but are not limited to: the package.xml format used by ROS, commonly-used message definitions, the API for ROS executors, and the format of traffic network information ingested by Open-RMF.
3. Meta - These documents specify the REP system, its processes, involved parties, etc. Meta-REPs have an REP Number below 100; no other REP types are allowed a REP Number below 100.

“Generally agreed best practices”, “recommendations”, style guides, documentation on tools, and release schedules are typically out of scope for REPs and shouldn’t be proposed through the processes described in the REP Meta documents. A REP is a ratification of a successful design, and this should be used as the guiding principle for determining if something is appropriate to be a REP. In all cases, if unsure, ask in the Open Robotics Discourse for clarification.

Below is a mapping from types for REPs created using the previous process (documented in REP-0001:2010 and REP-0001:2012) to the types available in process given in this document.

1. REP-0001:2012 “Standards Track” REPs are treated as “Standard” REPs.
2. REP-0001:2012 “Information” REPs are treated as “Specification” REPs.
3. REP-0001:2012 “Process” REPs are marked as superseded, and no longer in effect.

REP Workflow

Important terms

1. Author - A person who contributes to the initial writing of the REP. Although a REP may initially be written by more than one Author, for organisational purposes a single Author must be identified as the Lead Author.
2. Lead Author - The author of the REP who takes the lead in organising its proposal, shepherding discussion, building consensus, and communicating with the Sponsor, the REP Editors and the community.
3. PMC Sponsor - The person who coordinates with the Lead Author to manage the REP as it goes through the formal REP process. The PMC Sponsor must be someone who is a PMC Member in at least one of the PMCs relevant to the REP.
4. Draft REP - A REP that has begun the formal process of being accepted or rejected, but has not yet reached either of those states.
5. Accepted REP - A REP that has gone through the formal REP process and been accepted.
6. Finalized REP - A REP that has been accepted, merged into the repository, is published on the public REP website, and has any necessary implementation finished and merged.
7. Rejected REP - A REP that has gone through the formal REP process and ultimately been rejected by the relevant PMCs.
8. Superseded REP - A REP that has been superseded by a newer Finalized REP, and is therefore no longer applicable.
9. Withdrawn REP - A REP that has been withdrawn from the REP process by the authors (either intentionally or through inaction) prior to being accepted.
10. Deferred REP - A REP on which progress has stalled prior to being accepted.
11. REP Repository - The GitHub repository that stores all REPs from Draft REP status onward. Located at https://github.com/openrobotics/reps.
12. REP Editors - The group of people who maintain the REP Repository, and in particular are responsible for reviewing and merging PRs that add Draft REPs to the repository and change the status of REPs.
13. REP Number - The unique identification number of a single REP.

Workflow overview

The process of creating a REP is roughly the following.

1. Identify the need for a REP and vet the idea publicly to verify the validity of the idea and the need for a REP.
2. Write the REP document, following the required structure and file format(s).
3. Find a sponsor and submit the REP so that it becomes a Draft REP.
4. Promote and facilitate discussion of the Draft REP amongst the user, developer and contributor communities, as well as in the relevant PMC(s).
5. If appropriate, produce an implementation of the Draft REP.
6. Have the Draft REP voted on by the appropriate PMC(s) to approve its promotion to Accepted REP.
7. Finalise the Accepted REP so it becomes a Finalized REP.

Detailed workflow description

Step 1: Identify the need for a REP

The REP process begins with a new idea for one or more of the projects. When deciding whether to propose a new REP, it is important to remember that bug fixes and many enhancements/new features do not need to be a REP. These should instead be submitted directly to the GitHub issue tracker for the relevant repository or, if you’ve already fixed the bug or implemented the enhancement, submitted as a Pull Request (PR) to the relevant repository. This is a much faster and lower-effort way to get your proposal accepted for small changes. If you submit a proposed new feature that the maintainers of the project feel is significant enough, they may request that you produce a REP, but by already having an implementation, you will have a headstart on the process.

A single REP must contain only one key proposal. Focused REPs are more easily accepted and more easily adopted by the community. REP Editors have the right to reject a proposed REP if they believe it is too unfocused or too broad. If in doubt, split your REP into several well-focused ones that can be worked through one at a time.

Each REP must have a Lead Author. This is the person who takes the lead on writing the REP (following the required REP style and format described below), starts and shepherds discussions about the proposal, and attempts to build a consensus in the community around the proposal.

The Lead Author should first determine if the idea is suitable for a REP. Doing this vetting before beginning to write the REP is intended to save the Lead Author unnecessary time and effort. The idea might be more suited to going straight to a Pull Request, it might not be appropriate for some reason the Lead Author has not thought of, it might have already been tried and failed (and an Internet search by the Lead Author has not turned this up), or there might be input from others in the community that improves the idea before too many words are written. This vetting also helps the Lead Author understand whether an idea that sounds good to them is actually good for the community as well.

Ideally, at least a small proof-of-concept will be available when the idea is first proposed. This helps to focus discussion and practically demonstrates the feasibility of the idea.

The best place to begin getting feedback on an idea is to make a topic in the -Ideas category of the relevant Project at the Open Robotics Discourse. For example, if the idea is relevant to ROS, post in the ROS Ideas category below the ROS Project. If another category might be more suitable, post in the -Ideas category for the most relevant Project first, and the Open Robotics Discourse moderators will move your post to a more suitable category if necessary. The Lead Author can then answer questions about their idea and incorporate feedback from the community if they begin writing a draft REP. Note that it is important not to post the idea in the -Ideas category of a project that is not relevant. If the idea is relevant to more than one project, post the idea in the -Ideas category for the most relevant project, and post a brief pointer to your topic in the -Ideas category for other relevant projects.

It is up to the Lead Author to decide when they feel they have discussed the idea enough to begin writing a draft REP. This is the point when discussion evolves from discussing whether to write a REP, to discussing the content of the REP itself.

Step 2: Write the REP

Following the discussion on the validity of the idea, it is time to start writing a draft REP. The Lead Author should follow the information in the REP Formats section for guidance on file format, text formatting, how to add the header, and any other specific content required by the REP process.

Once the draft is sufficiently complete (where “sufficiently” is left up to the authors to define), the Lead Author should make a post about it to the same forum as in Step 1 for feedback from the community. This gives the Lead Author a chance to get additional feedback, particularly about details not discussed during the initial idea vetting. They can also receive feedback about format, quality of the content, and any initial concerns that might come up later in the REP process. Doing this now will likely save the Lead Author time later in the process.

It is important to emphasise the value of having discussion with the community, especially members of the relevant PMCs, prior to moving on to the next step, and from as early as the authors feel comfortable doing so in their writing process. Early discussions can reveal necessary changes and additions, and therefore save the authors time later in the process. Discussions at this stage can also help kickstart the process of finding a PMC Sponsor, which is essential to complete Step 3.

Step 3: Move the REP to Draft REP status

Once the draft of the REP document and any supporting media is complete, the Lead Author needs to get it turned into a formal Draft REP.

The first step in making the proposed REP a Draft REP is to find a PMC Sponsor to help the Lead Author throughout the REP Process. The role of the PMC Sponsor is to provide guidance to the Lead Author as they work through the REP process.

To find a PMC Sponsor, the Lead Author should contact the PMC(s) relevant to the topic of the REP, and ask for one of the PMC Members to sponsor their REP. Ideally, the Lead Author will have the PMC Sponsor found for them by virtue of someone in one of the relevant PMCs showing interest in the proposal during Steps 1 and 2, and volunteering to be the PMC Sponsor. If not, the Lead Author should make a post in the -Ideas categories at the Open Robotics Discourse for the relevant Project(s), explicitly asking for a sponsor. If no sponsor is forthcoming, then the Lead Author should consider this a sign that the idea needs more work before becoming a Draft REP.

If the Lead Author is themselves a member of a PMC relevant to the REP’s topic, then they are not required to find a PMC Sponsor. If the Lead Author is not a member of a relevant PMC but one of their co-authors is, then that person is the most appropriate, but not required, to be the PMC Sponsor.

Once identified, the Sponsor needs to be recorded in the PMC Sponsor: field of the REP’s header. The relevant PMCs need to be recorded in the PMCs: field of the REP’s header.

The PMC Sponsor will help the Lead Author decide when their proposed REP is ready for submission to the REP Repository to become a Draft REP. This includes not just the formatting but also the content.

The Lead Author should then follow the process below, with the assistance of the PMC Sponsor, to submit their REP.

1. The Lead Author forks the REP Repository, switches to a new branch for their addition, creates a directory named rep-NNNN, where NNNN is the next available REP number not used by a published or in-PR REP, and within that directory creates a file named rep-NNNN.md. See the “REP naming and numbering” section for more information.
2. The Lead Author fills in the known header fields in their new file, as appropriate. Most importantly, the REP: field must be set to the same number as used in the filename, and the Status: field must be set to Draft. For full details, see the REP Header section, below.
3. The Lead Author updates the CODEOWNERS file to list, for the new REP’s directory, any co-authors or PMC Sponsors who are REP Editors (in other words, they have write access to the REP Repository). This will allow those people to be automatically assigned to any pull requests that change the file.
4. The Lead Author pushes their changes to the fork they created in step 1, and submits a pull request to the REP Repository.
5. The REP Editors review the PR for general errors, confirming that the proposed REP meets the minimum readiness criteria.
   1. The REP is sound and substantially complete, and the ideas make technical sense. The REP Editors do not consider whether the ideas seem likely to be accepted.
   2. The title accurately describes the content.

   3. The language and code style used in the REP are correct and conformant with required structure and formatting for REPs. This includes checking the file for correct Markdown formatting.

      The REP Editors are permitted to be lenient in this initial review, as the process before acceptance of a REP will generally fix problems in structure and grammar. However, correctness is the responsibility of the authors, especially the Lead Author, and the REP Editors may send the PR back to the Lead Author for revision, with specific instructions.

6. Once the PR is approved, the REP Editors will formally assign the REP a REP Number. Note that this does not mean that the REP has been approved or accepted, only that it has been accepted as a Draft REP. The REP Editors will then squash-commit the pull request onto the main branch of the REP Repository.

The REP does not need to be entirely complete when the first pull request is submitted; sometimes it can be beneficial to have a REP Number assigned earlier for ease of reference and distinguishing it from other REPs being considered at the same time. The REP Editors may judge whether they consider a REP “complete enough” to assign a REP Number.

The REP Editors may not unreasonably deny publication of a new Draft REP. Reasons for denying a PR include duplication of effort, being obviously technically unsound, not providing proper motivation, and not being in keeping with OSRF’s open source philosophy. The REP Editors may consult with the OSRA’s Technical Governance Committee (TGC) or with any individual Project Management Committee (PMC), if they see a need to. In cases of disagreement, the final arbiter of a REP’s viability is the TGC.

REP Editors may propose a new REP as a Lead Author. However, they must recuse themselves from REP Editor status in any work relevant to their REP, including reviewing the initial pull request.

Step 4: Discuss the Draft REP

(This step should be conducted in parallel with step 5.)

Once the REP Editors have assigned a REP Number and merged the pull request, the Lead Author should create a discussion topic for the Draft REP in the -Ideas sub-category of the most closely-related project’s category on the Open Robotics Discourse. For example, a Draft REP that is closely related to ROS should have its discussion topic created in the REPs sub-category of the ROS project category. The REP document should be updated (via a PR) to include a link to this topic in the Discussion: header field.

The opening post of the topic should link to any other topics where the Draft REP was previously discussed, such as a topic in the Ideas category. It is also recommended that the Lead Author announce the discussion topic in the REPs room on the OSRF’s chat server.

Substantial discussion of the REP should happen in this public topic, rather than in other channels. This is intended to avoid fragmenting discussion and ensure that all interested people see all ideas discussed. However the Authors are free to engage in discussions and gather feedback in other relevant venues if they feel it is appropriate. For example, it is accepted that discussion of a REP is likely to happen in PMC meetings of the relevant PMCs, and in the OSRF’s chat servers. The authors should in general bias towards public discussion, and when discussion happens in another venue (such as a meeting), it is the responsibility of the authors to take notes of those discussions and post them to the public topic. Failure to do so is likely to delay acceptance of the REP. Avoid holding substantial discussions in GitHub issues on the REP Repository, or in wide-scope pull request reviews. GitHub’s discussions can quickly become difficult to follow and automatic comment hiding can hide important information.

The Lead Author may create a new topic in the same category if, during the discussion and implementation phase, the Draft REP undergoes a significant re-write or other substantive changes to its content.

The Lead Author and any other Authors are responsible for collecting community feedback on their Draft REP before submitting it for acceptance review. However, because gathering such feedback in a public forum can sometimes become long-winded or controversial, it is highly recommended that the Lead Author also request private feedback from key community members, such as PMC Members for the relevant projects, early in the process, as well as collaborate with other community members who have expertise in the Draft REP’s subject matter. The Authors should use their discretion to obtain useful and relevant feedback. However, this does not permit the Lead Author to skip creating the public discussion thread; a REP that has been developed primarily in private is unlikely to be accepted; the public discussion is a critical part of what will be reviewed when considering the Draft REP for acceptance.

Draft REPs are under free discussion, and changes to the document itself may be proposed at any time by the authors. Changes must be made by submitting a pull request to the REP Repository with the proposed changes. Only REP Editors may merge PRs into the REP Repository; they will perform the same checks to proposed changes as they do for a newly-submitted REP.

Before making substantive changes to a Draft REP, it is strongly recommended to propose and discuss those changes in the REP’s discussion thread.

If, during this discussion phase, the REP Editors determine that progress on the Draft REP has stalled, they may mark the REP as Deferred, marking this in the REP’s header and including the rationale for this change in the PR to the REP Repository that makes it. Typically, the REP Editors will make this decision when the authors (especially the Lead Author) has stopped interacting with the REP Process, or has in general vanished (is not reachable by email or other known contact methods, is not attending meetings, and similar). However the REP Editors do have the right to move a Draft REP to Deferred status for any other sufficient reason; such decisions are appealable to the TGC.

Entering the Deferred state starts a timer on the REP. If, after a minimum of six calendar months in the Deferred state, the REP has not had any changes that would move it back to Draft status, the REP Editors may mark it as Withdrawn.

A Deferred REP can return to Draft status by a decision of the REP Editors; they may make this decision unilaterally or at the request of one of the Authors or one of the relevant PMCs. A PMC will typically only make this request when they have one or more new authors available to take over the work on the REP; in this situation, the REP Header will be updated to include the new Authors, and specify the new Lead Author. The existing author names must not be removed. The REP Editors may refuse to return a Deferred REP to Draft status for sufficient reason; such decisions are appealable to the TGC.

Step 5: Implement the Draft REP

(This step should be conducted in parallel with step 4.)

A Draft REP may require an implementation before it can be accepted; for some it may be a reference implementation but in most cases it will be the final intended implementation, including comprehensive tests and documentation, that will be the actual implementation used “in production” in the project’s releases. Nearly all REPs will fall into this category.

Any proposed implementation must be appropriate to the target project(s) and follow their existing principles and policies, such as coding conventions, repository usage, and IP licenses. The implementation must also be acceptable to the relevant projects’ PMCs.

Producing an implementation is a crucial step in understanding the true technical feasibility and technical merit of a Draft REP. The Lead Author and other Authors should begin performing this work as early in the REP process as possible, but no later than when the REP is assigned a REP Number and moved to Draft status.

The implementation should be developed in public view, and referenced in the Draft REP’s discussion topic on the Open Robotics Discourse. Using an implementation to support proposals is one of the most sound ways to support an argument for the Draft REP.

The implementation does not need to be complete to a releasable level of quality in order for the Draft REP to be accepted. However, any implementation will be an important part of the review process, so it should be functional and substantially representative of the Draft REP’s content.

The implementation will need to be completed and merged into the project to mark the REP as Finalized, should it be accepted. The more implementation work that is completed prior to the acceptance review, the faster this final step after acceptance can happen (see Step 7, below).

Step 6: Acceptance of the Draft REP

The Authors may request a review of their Draft REP for style and consistency from the REP Editors at any time.

To move the REP from Draft status to Accepted REP, the authors and, if present, the PMC Sponsor must agree that the Draft REP is ready for final review and an acceptance decision, and formally request the start of the acceptance process.

The acceptance of a Draft REP is the responsibility of the relevant PMCs, as a single group. Which PMCs are relevant is determined by the REP Editors; they will also simultaneously determine which PMC is the most relevant and will lead the process. The TGC may overrule this decision, with reason.

Acceptance process

The acceptance process begins by the Lead Author opening an issue in the leading PMC’s issue tracker, submitting their Draft REP for acceptance. Alternatively, the TGC may, at its own discretion or when called on by a PMC, initiate the acceptance process before the Authors make their formal request. In doing so, the TGC must provide the Authors with notification and give them a minimum of one calendar week to make revisions.

As part of submitting the Draft REP for acceptance, the Lead Author should organise all relevant materials into a review packet. This includes providing pointers (URLs, PDFs, and similar) to relevant discussions, including private discussions the Lead Author has permission to share, ensuring that all necessary auxiliary files are available, and that the Draft REP renders easily. Including a PDF of the full Draft REP, with auxiliary files included, is recommended. This information should be attached to the issue in the leading PMC’s issue tracker requesting a formal review for acceptance of their Draft REP.

The leading PMC will make a call to its own Members and the Members of all other relevant PMCs asking for one or more volunteers to conduct a review of the Draft REP. If no volunteers to conduct the detailed review step forward, then the REP shall be marked as Deferred. See Step 4 for more information on the Deferred status.

It is the job of the volunteer reviewers to perform a detailed review of the Draft REP, including the document itself, any supporting documents, any reference/prototype implementation, public discussions that have taken place, and any other relevant materials. The reviewers shall produce a report for the relevant PMCs, concluding with a recommendation to either accept or reject the REP. The report shall include, but may not be limited to, evaluating the following criteria of the Draft REP.

1. Is the REP a clear and complete description of the proposed enhancement?
2. Is the REP a net improvement (i.e., it may degrade or remove some aspect of the project(s), but in doing so provide something better)?
3. Is the implementation, if any, solid and not unduly complicated?
4. Is the proposed implementation substantially complete, including appropriate tests, infrastructure changes, documentation, and any other relevant work completed, and could be merged without significant changes to the implementation?
5. Has the REP been sufficiently (in the eyes of the reviewers) discussed by the community? In particular, has there been any input from existing project members of the relevant projects?
6. Have any reasonable issues raised during public discussion been addressed by the Authors? (Note that this does not require accepting an issue as valid, but the Authors do need to address it with a reasonable decision and explanation.)
7. Have the Authors been timely in their actions throughout the process, and are they likely to be timely in producing a final implementation suitable for being merged into the relevant project(s)?

Once the reviewers have provided their report, the leading PMC shall call for a decision on whether to accept or reject the Draft REP. The decision may be preceded by discussion if a Member of any relevant PMC requests one. The discussion may happen in a teleconference or in an asynchronous forum, at the PMC Members’ discretion. The Lead Author or any other Authors may be involved in this discussion if requested by any Member of any relevant PMC, or they may be questioned independently of this discussion.

The decision to accept the REP shall be made through the following process.

1. The leading PMC shall call for a decision on approving the reviewers’ recommendation to accept or reject, notifying all Members of all relevant PMCs and asking for any objections.
   1. If no objections are received, the recommendation of the reviewers is approved by consensus.
   2. If at least one objection is received, a vote is started. Each Member of each relevant PMC, including the reviewers, receives one vote, and votes to either accept the Draft REP, reject the Draft REP, or abstain. A quorum of 50% of the involved PMC Members (all PMC Members of all PMCs that were judged as relevant by the REP Editors) is required for the decision to be valid, with a simple majority of those voting being required to determine the outcome.
2. Once the decision to accept or reject has been made, it is reported to the TGC by the leading PMC.
   1. If the decision was made by consensus, the TGC may overrule the decision but must publicly provide their reason for doing so, and this decision is appealable to the Board of Directors of the OSRF by any Member of the relevant PMCs or by the Lead Author of the REP.
   2. If the decision was made by a vote, the TGC has the right to inspect the discussions prior to the vote and understand who objected and why. The TGC may then overrule the decision, but must publicly provide their reason for doing so. An overruling is appealable to the Board of Directors of the OSRF by any Member of the relevant PMCs or by the Lead Author of the REP.

Upon the final decision to accept or reject being made, the status of the Draft REP shall be updated in the REP Repository to either Accepted or Rejected, as appropriate. The decision to accept or reject shall be announced in the REPs sub-category of each relevant project as well as in the PR which makes the status change.

At any time during, or prior to, the acceptance process, the Lead Author, in agreement with the other authors and, if there is one, the PMC Sponsor, may withdraw the Draft REP. This leads to the REP’s status in the REP Repository being set to Withdrawn and an announcement being made in the REPs sub-category of each relevant project as well as in the PR which makes the status change. An example of why this might be necessary is when multiple competing proposals are moving through the process in parallel, and the authors of one proposal have decided that another proposal is a better approach.

In the rare case where a Draft REP has only one relevant PMC, and all Members of that PMC are involved in the Draft REP as co-authors, the role of “PMC” in the above process shall be filled by the TGC or, at the discretion of the TGC, another PMC, as nominated by the REP Editors and agreed to by the TGC.

Step 7: Finalise the Accepted REP

An Accepted REP must be finalized before it can become a Finalized REP. This process requires the following to be performed.

1. The REP Editors, in cooperation with the Authors as necessary, finalise the formatting of the REP document to ensure it is displayed correctly when rendered on the REP website.
2. The Authors complete the implementation, if any, and submit it for merging into the relevant projects via the appropriate process (such as a GitHub pull request). The implementation is merged such that it will be included in the next appropriate release.
3. If the Accepted REP supersedes one or more existing REPs, those superseded REPs have their status set to Superseded.

Once all of the above are completed, the Accepted REP becomes a Finalized REP, and the REP Editors set the REP’s status in the document to Finalized.

If changes become necessary based on implementation or user feedback when the REP is moving from Accepted to Finalized, those changes may only be made with the approval of the TGC. The changes must be made via a pull request to the REP Repository. The REP document must accurately describe the implementation at the point when the REP is marked Finalized.

If progress on any of the above stalls, such as polishing the implementation revealing fundamental flaws that were not, until then, obvious, the Accepted REP may be rejected by a decision of the relevant PMCs. Any implementation work already merged may be removed following the usual processes for the relevant projects, such as going through a deprecation cycle.

REP Editor responsibilities

All REP Editors must be in the rep-editors group on the REP Repository, and have notifications on this repository set to the Watching level.

REP Editors do not pass judgement on REPs. Their role is to do the administrative and editorial tasks involved in maintaining the REP Repository, and the REP website published from it.

For each new REP submitted to the REP Repository via a pull request, a REP Editor must do the following.

1. Ensure that the REP has a person who is a member of one or more of the most relevant PMC as a PMC Sponsor, or that the Lead Author is themselves a member of one or more of the most relevant PMCs.
2. Confirm that the correct relevant PMCs are listed in the PMCs: field of the REP Header.
3. Read through the REP to check that it is sound and complete, the ideas make technical sense (whether or not they are likely to be accepted is not relevant to this check), there are no obvious large errors in language (spelling, grammar, sentence structure, formatting, etc.) and code style, and that the REP is in general ready. REP Editors are not required to correct problems themselves, but may do so if they wish to.
4. Check that the title accurately describes the content.
5. Check that the file’s extension is .md.
6. Confirm that the file’s format is broadly correct; because the REP is expected to undergo heavy editing via PRs after this point, the one-sentence-per-line rule must be followed.
7. Confirm that all co-authors and the PMC Sponsor (if any) who have write access to the REP Repository are added to CODEOWNERS.

If the REP is not yet ready, a REP Editor shall send it back to the Lead Author for revision, with specific instructions.

Once the REP is ready for merging into the REP Repository as a Draft REP, a REP Editor shall do the following.

1. Check that the Lead Author has selected a valid REP Number, or assign them a number if they have not. This should typically be the next available REP Number. Numbers below 100 are reserved for meta-REPs.
2. Check that the Lead Author has correctly labeled the REP’s type in the REP Header (Standard, Specification or Meta) and marked the REP’s status as Draft.
3. Ensure that all CI checks, including linters, pass without errors, and that the rendered output has no obvious errors.
4. Merge the pull request.
5. Inform the Lead Author of the next steps (Step 4 of the REP Workflow).

Maintenance of REPs

In general, REPs are no longer substantially modified after they have reached the Accepted, Finalized, Rejected or Superseded state. Once a resolution has been reached, a REP is considered a historical document, rather than a living specification. Documentation of behaviour should be provided elsewhere, such as API documentation and user documentation.

Meta-REPs may be updated over time to reflect changes in the processes and practices they describe. The process for updating a Meta-REP is the same as for submitting a new REP, but with the advantage of starting from a known-accepted state.

A Deferred REP may be resurrected by the Lead Author, one of the co-authors, or anyone else, through major updates. However it is generally better to propose a new REP rather than resurrect a Deferred REP that you are not an author on.

A Withdrawn REP is not able to be resurrected. Begin a new REP, and include an appropriate amount of content from the previous REP, with appropriate acknowledgement.

Below is a mapping from statuses for REPs created using the previous process (documented in REP-0001:2010 and REP-0001:2012) to the statuses in the process given in this document.

1. REP-0001:2012 “Draft” is equivalent to “Draft”.
2. REP-0001:2012 “Accepted” is equivalent to “Accepted”.
3. REP-0001:2012 “Rejected” is equivalent to “Rejected”.
4. REP-0001:2012 “Withdrawn” is equivalent to “Withdrawn”.
5. REP-0001:2012 “Deferred” is equivalent to “Deferred”.
6. REP-0001:2012 “Final” is equivalent to “Finalized”.
7. REP-0001:2012 “Replaced” is equivalent to “Superseded”.
8. REP-0001:2012 “Active” has no equivalent; these REPs are Final until Superseded.

Content of a REP

Each REP should have the following parts.

1. The REP Header, specified using RFC 2822 format. Required.
2. Abstract - A short (about 200 words) description of the topic being addressed by this REP. Required.
3. Motivation - Explains why the REP is necessary. This is particularly critical for any REP that specifies or changes APIs. The motivation must clearly explain why existing practice, software, or other relevant information are not sufficient to address the problem that the REP intends to solve. REP submissions without sufficient motivation may be rejected. Required.
4. Specification - The technical specification, which makes up the major part of the REP’s content. The specification must be detailed enough to allow competing, interoperable implementations. Required.
5. Rationale - Describes why particular design decisions were made. When necessary, describe alternate designs that were considered and any related work, including in other similar open-source or closed-source projects. The rationale should demonstrate, through evidence, consensus in the community, which includes discussing important objections or concerns raised during discussion, and how they were addressed. Required.
6. Backwards Compatibility - A REP that introduces backwards incompatibilities of any kind, including in dependent projects (such as through changing APIs), must include a section describing these incompatibilities, their severity, and how they can be dealt with. This includes how the REP authors intend to deal with the incompatibilities in the project itself and any other software they control. REP submissions without sufficient information on backwards compatibility may be rejected. Optional.
7. How to Teach This - For a REP that adds or changes user-facing behaviour, include a section on how to effectively teach both new and experienced users how to apply the REP. This section may include key points to emphasise when teaching, and recommended documentation changes to help users adopt a new feature or migrate their work to use the changes. Required.
8. Implementation - The implementation must be completed before the REP can be moved to the Finalized state, but it does not need to be completed for the REP to be Accepted. It is recommended that an implementation, as complete as possible, be produced in parallel with discussions, beginning once the REP’s content has reached enough of a steady state to do so, as the implementation can help resolve discussions. Prior to acceptance of a Draft REP, the implementation must include comprehensive tests and documentation; in general this implementation is expected to be the actual implementation that will be used “in production” in the project’s releases. Required.
9. Rejected Ideas - Throughout the discussion of a REP, ideas may be proposed which are ultimately rejected. Those rejected ideas should be recorded in this section, along with the reasoning as to why they were rejected. This provides insight into the design of the final version of the REP, and helps prevent people from bringing up the same rejected ideas again in subsequent discussions. This section can be referenced from the Rationale section. Optional.
10. Known Issues - While a Draft REP is being worked on and discussed, ideas can come up that warrant further discussion or require additional work. Recording those ideas in this section allows others in the community to know they are being thought about but are not yet resolved, both to ensure they are completed prior to accepting the REP and to help those new to the discussion avoid repeating prior discussion. Optional.
11. Copyright/License - Each REP must be placed under the CC0-1.0-Universal license, and this must be stated explicitly in the REP document. Required.

REP Formats

REP naming and numbering system

REPs are numbered using incrementing integers, starting at 1. When specified in REP Headers and in file names, REP numbers are left-padded to four digits with zeroes, e.g. 0001.

To support future version capability in the REP Process, the REP number may optionally be followed by a colon and the year that the REP was accepted, as a way of indicating the version of the REP complied with. For example, when specifying the version of REP 1734 as accepted in the year 2027, specify REP 1734:2027. When this year value is not provided, as in REP 1734, then the most recent version of the REP shall be assumed.

REP Numbers less than 100 are reserved for Meta-REPs.

The next available REP Number is usually the most-recently-assigned REP Number plus one. However, the REP Editors may, at their discretion, assign a REP Number out of this sequence. If the most-recently-assigned REP Number plus one has already been taken by an earlier REP, then the next available REP Number is used, repeating until an available REP Number is found.

File format and location

REP documents are UTF-8 encoded text files in the Markdown format. The flavour of Markdown used must be compatible with the GitHub Flavored Markdown Spec Version 0.29-gfm. Within the file, lines must not be wrapped, and each sentence must start on a new line (i.e. each sentence is on its own line). This is necessary to ensure pull request diffs are sufficiently readable.

The file name of a REP document must be rep-XXXX.md, where XXXX is the REP Number. The REP file and any auxiliary files, such as images, must be placed in a directory named rep-XXXX, where XXXX is the REP Number.

A template REP is available in REP-0004:2025. It is recommended that this template be used when starting to write a new REP.

REP Header

The REP Header must contain the following fields, specified in RFC 2822 format.

REP: <REP Number> Title: <REP title> Author: <List of authors’ names, optionally with email addresses or GitHub usernames; the Lead Author must be first> PMC Sponsor: <Name of the PMC Sponsor, or Lead Author if no sponsor is required> PMCs: <Names of the PMCs with relevance to this REP> Discussion: <List of URLs of the discussion thread(s) for this REP> Status: <Draft | Accepted | Finalized | Rejected | Withdrawn | Deferred | Superseded> Type: <Standard | Specification | Meta> Requires: <List of depended-on REP Numbers> Created: <Creation date, in ISO 8601 format as YYYY-MM-DD> Supersedes: <REP Numbers of any REPs this one supersedes> Superseded-By: <REP Numbers of any REPs that supersede this one> Resolution: <URL of the acceptance/rejection post> Resolution-Date: <Resolution date, in ISO 8601 format as YYYY-MM-DD>

The Author: and PMC Sponsor: fields must follow one of the following formats:

1. Random Person <random@example.com> if the person’s email address is included,
2. Random Person <randper@github> if the person’s GitHub username is included, or
3. Random Person if neither the email address nor GitHub username are included.

The person’s name does not need to be their legally assigned name, but it must be a name they use consistently throughout the community. Note that email addresses will be obscured, but still readable, in the rendered version of the REP.

If there are multiple authors, each should be on a separate line following RFC 2822 continuation line conventions.

The PMCs: field must use the names of PMCs as specified in their project charters. Meta REPs only may specify None in this field and in the PMC Sponsor: field.

The Created: field specifies the date that the REP was officially assigned a REP Number and first merged into the REP Repository.

The Requires: field is optional. When used, it specifies the REP Numbers of other REPs that this REP depends on.

A REP that supersedes one or more previously Finalized REPs must list the numbers of those REPs in the Supersedes: field. Additionally, when the superseding REP is marked Finalized, those superseded REPs must have the Superseded-By: field added to their headers with the number of the superseding REP(s).

Auxiliary Files

REPs may include additional files, such as diagrams and sample source code files. Auxiliary files must be placed in the REP’s directory. There are no restrictions on filenames for auxiliary files.

REP Checklist

When suggesting a new REP, use this checklist to ensure that you have done everything necessary. This will help the REP Process go smoothly.

1. Make a post about your idea at the Open Robotics Discourse and gather feedback about the appropriateness of producing a REP for it.
2. Verify that your REP source file (in Markdown) complies with the formatting requirements in REP-0001:2025 and REP-0004:2025.
3. Verify that the Header is complete.
4. Verify that your REP contains all required sections, with content as appropriate.
5. Find a PMC Sponsor by discussing with each relevant PMC and requesting a sponsor from those PMC Members who show interest.

License

This document is marked CC0 1.0 Universal. To view a copy of this mark, visit https://creativecommons.org/publicdomain/zero/1.0/.