Sample Markdown REP Template

Posted Aug 19, 2025 Updated Oct 17, 2025 Type: Meta Status: Finalized View REP Source

By Geoffrey Biggs

5 min read

Abstract

This REP provides instructions on formatting REP documents correctly, and a template REP document. In conjunction with the content guidelines in REP 1, this should provide REP authors with everything they need to produce a conforming REP document.

Important note: If you are reading this REP in your web browser, you should go to the raw Markdown source file file (with a .md extension) to get the template. Do not use the rendered document or HTML source as your template.

The source for this REP, and all REPs, can be found in the REPs repository, as well as via a link in each rendered REP.

Motivation

Anyone submitting a REP must use this template, in conjunction with the format guidelines below and in REP-0001:2025, to ensure that your REP submission won’t get automatically rejected or otherwise delayed because of formatting errors.

Markdown is a well-known, widely-supported format for structuring text documents for rendering while also being easy to read in the source form. The document rendered from a Markdown source file, in formats such as HTML and PDF, provides accessibility to readers, with live hyperlinks, styled text, tables, inlined images, automatic table of contents generation, and other such features.

How to use the template

Follow these steps to use the template and begin drafting your proposed REP.

Make a copy of this file (the source .md Markdown file, not the HTML, PDF, or other displayed document), or the raw template available in the REP repository.
Rename your new file to rep-NNNN.md, where NNNN is the next available REP number (which you can find by browsing the list of REP files in the repository and checking the active PRs) not used by a published or in-PR REP.
In the header, replace REP: 0004:2025 with REP: NNNN:YYYY, where NNNN should match the filename and YYYY is the current year.
Change the Title in the header to that of your REP.
Change the Author field to include your name and optionally either your email address or your GitHub username. Your name, as the Lead Author, should appear first. Follow the field format defined in REP-0001:2025, section “REP Header”, exactly. You may obfuscate your email address if you choose; even if you do not, it will be automatically obfuscated in rendered versions of the REP.
Change the PMC Sponsor field to be either the sponsor of your REP, or blank if no sponsor has yet been found, or to the Lead Author, if no sponsor is required.
Add the full URL to all relevant discussion threads on the Open Robotics Discourse to the Discussion field. Do not use link shorteners. If no discussion thread yet exists, use Pending for this field, but remember to update the field with the discussion thread links once they become available, or your REP will not be accepted.
Set the Status field to Draft.
Set the Type field to Standard or Specification, as appropriate.
Fill in the Requires field, if your REP depends on other REPs.
Set the Created field to today’s date. Follow the format exactly, using ISO 8601 format as YYYY-MM-DD.
Fill in the Supersedes field, if your REP will make one or more existing Finalized REPs obsolete.
Write the Abstract, Motivation, Specification, Rationale, and any other necessary sections for your REP. Replace all the existing text from the original file with your own.
Create a pull request against the REPs repository to add your REP as a draft.

Other than the Header, which must be in RFC 2822 format, all content in the REP’s source Markdown file must comply with the GitHub Flavored Markdown Specification. 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.

Example Markdown

The following is a brief example of a Markdown source for a REP.

REP: REP-0343:2038 Title: Example Markdown for a REP Author: Jessica Leadauthor <jessica@example.com> PMC Sponsor: Jane Sponsor <j.sponsor@example.com> PMCs: ROS Discussion: https://discourse.openrobotics.org/t/34573894 Status: Draft Type: Specification Requires: REP-0218:2029, REP-0113:2032 Created: 2038-08-19

# Abstract

[A short (about 200 words) description of the topic being addressed by this REP.]

# Motivation

[Explains why the REP is necessary.]

# Specification

[The technical specification, which makes up the major part of the REP’s content.]

# Rationale

[Describes why particular design decisions were made.]

# 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.]

# 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.]

# 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]

# Rejected Ideas

[Throughout the discussion of a REP, ideas may be proposed which are ultimately rejected.]

# Known Issues

[While a Draft REP is being worked on and discussed, ideas can come up that warrant further discussion or require additional work.]

# Copyright/License

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

Resources

Information about the Markdown format can be found at Wikipedia, as well as the original Markdown website.

The variant of Markdown used in REP documents is GitHub Flavored Markdown. The specification is available online, as is an explanatory article describing why the variant exists.

License

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