OEP-1: OEP Purpose and Guidelines#

OEP

OEP-1

Title

OEP Purpose and Guidelines

Last-Modified

2022-06-22

Authors

Calen Pennington <cale@edx.org>, Joel Barciauskas <joel@edx.org>, Nimisha Asthagiri <nimisha@edx.org>, Feanil Patel <feanil@axim.org>, Sarina Canelake <sarina@axim.org>

Arbiter

Status

Accepted

Type

Process

Created

2016-03-26

Review Period

Resolution

open-edx-proposals#1 resolution

References

Overview#

  • An Open edX Proposal specifies a best practice, architectural decision, or community process that the Open edX community has agreed should be adopted by the project.

  • OEPs are not used to dictate small decisions made in every day feature work. See OEP-19 for more detail.

  • This document specifies both how to write an OEP and how to get to a consensus throughout the community that the OEP should be accepted.

  • OEPs are written by one or more Authors and guided through the process by an Arbiter.

What is an OEP?#

OEP (pronounced “oh-epp”) stands for Open edX (Enhancement) Proposal. An OEP is a document that details a specific technology decision being made by the Open edX community, in the form of a best practice, architecture design, or process adjustment. An OEP should provide the use cases and rationales that surround that choice. OEPs are not the only way for a change to be made to Open edX, however. The goal is to create a collection of OEP documents as a repository or knowledge archive of architectural choices made for the platform.

Small enhancements or patches often don’t need an OEP and can be injected into the Open edX development workflow with a patch submission.

OEP templates are available to help you provide all of the necessary information for your proposal.

OEP Types#

  • A Process proposal describes a change to how the Open edX community functions.

  • A Best Practice proposal describes a technology or implementation choice that the Open edX community believes all applicable Open edX services and/or libraries should use or follow.

  • An Architecture proposal describes a concrete design problem with several potential solutions and the rationale behind the decision. The decision may be specific to a significant Open edX feature or a cross-cutting technical need.

OEP Roles#

Authors#

Each OEP must have at least one Author: someone who writes the OEP using the style and format described here, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea.

Step 1. Find an Arbiter lays out ways to get in touch with the community to find an arbiter; those channels may also be used to find a co-author, which is encouraged.

Arbiter#

Each OEP also has an Arbiter (as described in Step 1. Find an Arbiter). An Author of an OEP cannot concurrently be the Arbiter of that OEP.

In brief, the Arbiter…

  • Is knowledgeable about the contents of the proposal, while also being able to fairly hear all sides of a discussion.

  • Helps the Authors move the OEP through the OEP Workflow, namely:

    • As described in Step 3. Review with Arbiter, the Arbiter does a first review pass and establishes the length of the review period (see Review Period).

    • During the review period, the Arbiter keeps discussions on track and guides them towards resolution.

    • At the end of this period, the Arbiter decides if the OEP should be accepted, rejected, or remain open for additional discussion.

The Arbiter will be the person making the final decision on whether the OEP should be Accepted, and as such, the Arbiter should be knowledgeable about the contents of the proposal, and willing to listen to arguments both for and against it by the rest of the community.

The Arbiter is also responsible for helping the Authors move the proposal through the OEP process, providing technical and process expertise as needed. The Arbiter also assists the Authors in soliciting feedback from the community on the OEP and moving it towards a final decision (whether that decision is Accepted, Rejected, or Deferred). The Arbiter (in discussion with the Authors) can merge an in-progress OEP (if it has reached a stage of relative stability) to allow for additional incremental updates.

Architecture Group#

The Architecture Group serves as a backstop for the OEP process. Specifically, the group can assist in finding an Arbiter for an OEP if the Author is having trouble getting one for a new OEP or revived OEPs that need a new Arbiter (if the original Arbiter is no longer available). It is best practice for the Arbiter to be from a different team or group than the Author.

If there is uncertainty about a choice of Arbiter, it is reasonable to start a discussion with the group. The group can also be a resource to help or advise the Arbiter with the OEP process. The group can be found in the Architecture Group Discourse category or the #architecture channel in the Open edX Slack.

Note: If an architecture or similar working group is created, those details should be added here. Currently, the phrase “Architecture Group” refers to the set of community members who are active in the ``#architecture`` channel.

OEP Workflow#

Submitting an OEP#

Step 1. Find an Arbiter#

When writing an OEP, you may already have an idea of an Arbiter in mind. If so, reach out to that person and ask them; they should have the domain expertise needed to be an effective Arbiter and the time to do so. It is best practice for the Arbiter to be from a different team or group than the author.

If you’re not sure who would make a good Arbiter, you should reach out to the Architecture Group; please feel free to participate in the discussion and help choose an arbiter you feel you can work with. If you have concerns about an arbiter that has been chosen for a particular OEP, please share them with the author first and see if you can resolve your concerns directly. If you continue to have concerns, please share them in slack or Discourse, ideally on the original conversation thread. If you feel you can’t share concerns publicly, see our code of conduct for information on getting direct assistance.

Once found, this Arbiter will be recorded in the “Arbiter” header on the OEP.

Step 2. Create PR for “Draft” OEP#

Draft an OEP using one of the OEP templates and submit as a pull request against the central OEP repository. To identify the draft proposal, the Authors should check the numbered list of previous OEP pull requests and select the next available number.

The pull request title should be of the form “OEP-XXXX: <OEP title>”, where XXXX is the OEP number claimed for the included proposal.

Step 3. Review with Arbiter#

Once an Arbiter has been assigned to your OEP, establish begin and end review dates with your Arbiter, making it officially “Under Review”. Once this state is achieved, announce the OEP to the community in the following channels:

The Open edX community is given the opportunity to comment on the OEP. The Arbiter serves to keep the discussion on track and to bring the review process to a final resolution.

OEP Status#

A flowchart of OEP statuses, from Draft to Under Review, then to Accepted, Rejected, or Withdrawn. There are 2 transitional statuses from Draft and Under Review: to/from Provisional and to/from Deferred. An Accepted OEP can be Replaced.

Draft#

The Authors are working on an OEP and then reviewing it with an assigned Arbiter.

Under Review#

The OEP is under discussion and being reviewed by the Open edX community, the Arbiter, and the Authors.

Accepted#

The Arbiter has accepted the OEP after review and discussion within the agreed upon review period.

Deferred#

No further progress is made on the OEP and so it is marked “Deferred”. The OEP Authors can change it back to “Under Review” when it is in progress again.

Provisional#

The OEP is reviewed and generally agreed upon, but not yet fully “Accepted” since it hasn’t been vetted and adopted in the platform. Once viable reference examples and platform adoption occurs, the OEP can transition back to Under Review and be Accepted.

Rejected#

The OEP is “Rejected” by the Arbiter. Perhaps after all is said and done it was not a good idea. It is still important to have a record of this fact.

Withdrawn#

Similar to “Rejected”, the “Withdrawn” status means that the OEP Authors themselves have decided that the OEP is undesired or that a competing proposal is a better alternative.

Replaced#

OEPs can also be superseded by a different OEP, rendering the original obsolete. In that case, the OEP’s status should be changed to “Replaced” and updated with a link to its superseding OEP.

Obsolete#

Over time some OEPs may become obsolete without being replaced by new guidelines. In this case the OEP’s status should be changed to “Obsolete” and the OEP should be updated with an explanation as to why the OEP is no longer relevant.

Status changes#

When an OEP is Accepted, Rejected, or Withdrawn, the OEP should be updated accordingly. In addition to updating the Status field, at the very least the Resolution header should be added with a link to the appropriate section of the PR, and the Last-Modified header should be set to the current date.

Please note that OEP statuses do not necessarily coincide with the status of the pull request that contains the OEP. For example, OEPs that have been rejected should still be merged, but should be marked with the “Rejected” status. This preserves the rationale and description of the OEP in the generated documentation.

Likewise, an OEP that is in Under Review, Provisional, or Deferred statuses can be merged to capture a set of edits, and to make the proposal more visible to community comment. From that point, additional pull requests can be opened to edit the OEP, until it converges to being either “Accepted” or “Rejected”.

When an OEP PR calls for significant work after it merges, add a link named “Follow-up Work” to the References section of the OEP header. Use the linked page to keep readers up-to-date on the plan for completing and/or implementing the proposal. For OEPs merging with the status of Draft or Provisional, a Follow-up Work link is required.

If an OEP has Draft or Under Review status and the PR is under review, you can either use the intended merged status (e.g. Provisional, Accepted, etc.), or you can clarify both the current and intended status using something like the following: “Under Review (=> Provisional)”. Either of these options is especially useful if the merged status is not intended to be Accepted.

OEP Maintenance#

Reporting OEP Bugs#

While a pull request that contains a proposal is open, comments should be made on that pull request, or by submitting a new pull request that targets the branch from which the OEP pull request was made.

OEP Stewardship#

Once a proposal becomes Accepted, stewardship of the OEP is given to the Architecture Group. This group is tasked with ensuring OEPs are up to date, those Authors proposing changes to OEPs follow the procedures outlined in this document, and assist in linking Authors with Arbiters when needed.

Submitting OEP Updates#

Once an OEP has merged to the open-edx-proposals repository (which can happen when the OEP is in any status, including “Under Review”), changes can be suggested to it via new pull requests. Whether those changes are included is up to the Authors of the OEP.

Updating Best Practice and Process OEPs#

A Best Practice or Process OEP may be updated even after it is “Accepted” as it evolves over time. These future edits/updates may be made by the original Authors of the OEP or by new Authors. A pull request should be created to update the OEP and go through the following steps:

  1. For small changes (eg formatting or minor updates reflecting how process has already evolved), finding an arbiter may not be required. Larger changes will benefit from having one. The Arbiter may remain the same as before or a new one may be found as detailed in Step 1. Find an Arbiter.

  2. Reach out to previous authors & arbiters, or comment on the original OEP’s pull request discussion, with your proposed update so those central to the original proposal can weigh in on changes.

  3. Follow the Step 3. Review with Arbiter process, with a review period of at least one week (for smaller changes).

Updating Architecture OEPs#

Architecture OEPs are generally not modified after they have reached the “Accepted” or “Final” state. However, they may be replaced by subsequent OEPs. (OEPs that are replaced are given the status “Replaced”.)

The choice of whether an edit to an OEP should be allowed or whether a new OEP should be published must be discussed with the Architecture Group. However, as a general guideline, the following updates would not require a replacement OEP.

  • Formatting changes.

  • Grammatical and spelling corrections.

  • Adding links to additional relevant resources and discussions.

  • Additional diagrams or clarifying material (as long as the Architecture Group agrees that the substance of the OEP isn’t changed).

The following updates warrant replacement OEPs.

  • Changing how a set of services is separated in an Architecture OEP (for example, splitting one service into two, or combining two services into one).

  • A change in decision that is significantly different from the previous.

Adding Additional Authors or Arbiters#

When updates are made beyond those of formatting changes, small corrections, or basic upkeep, the Author(s) who made the changes, as well as the Arbiter who saw the change through, shall add themselves to the corresponding sections in the OEP Header Preamble.

OEP Structure and Content#

OEP Format#

OEPs are UTF-8 encoded text files that use the reStructuredText format. ReStructuredText [8] allows for rich markup that is relatively easy to read, and can also be rendered into good-looking and functional HTML. OEPs are rendered to HTML using Sphinx.

OEP Templates#

Other than requiring that all OEPs have a consistent OEP Header Preamble, the rest of the OEP document can be customized according to whatever is needed to capture the decision(s), as deemed appropriate by the Authors and Arbiter.

To help guide Authors, here are a few ready-made templates that are available for use:

OEP Header Preamble#

Each OEP must begin with a ReST table with metadata about the OEP. The rows must appear in the following order. Rows in italics are optional and are described below. All other rows are required.

OEP

OEP-XXXX-YYYY-ZZZZ

Title

<OEP title>

Last Modified

<date string, in YYYY-MM-DD format>

Authors

<list of authors’ real names and optionally, email addresses>

Arbiter

<Arbiter’s real name and email address>

Status

<Draft | Under Review | Deferred | Accepted | Rejected | Withdrawn | Final | Replaced | Provisional >

Type

<Architecture | Best Practice | Process>

Created

<date created on, in YYYY-MM-DD format>

Review Period

<start - target end dates for review>

Resolution

<links to any discussions where the final status was decided>

Replaces

<OEP number>

Replaced-By

<OEP number>

References

<links to any other relevant discussions or relevant related materials>

  • The OEP header is a unique identifier for the OEP, consisting of

    • XXXX - OEP number claimed for the included proposal.

    • YYYY - abbreviated type of the OEP (i.e., “proc”, “bp” or “arch”).

    • ZZZZ - hyphenated brief (< 5 words) title of the proposal.

    The filename of the OEP should match the value of this header.

  • The Authors header lists the names, and optionally the email addresses, of all the authors/owners of the OEP. The format of the Authors header value must be Random J. User <address@dom.ain> if the email address is included, or Random J. User if the address is not given. If there are multiple authors, their names and addresses should appear in a comma separated list.

  • The Arbiter field is used to record who has the authority to make the final decision to approve or reject the OEP.

  • The Type header specifies the type of OEP: Architecture, Best Practice, or Process.

  • The Created header records the date that the pull request for the OEP was opened. It should be in YYYY-MM-DD format, e.g. 2016-04-21.

  • The Review Period header specifies the target dates for reviewing the OEP, as agreed by the Authors and Arbiter. The recommended duration of the review is 2 weeks. However, if the review exposes areas of the proposal that need further discussion and fleshing out, then the Arbiter may choose to extend the review period.

  • OEPs can also have a Replaced-By header indicating that a OEP has been rendered obsolete by a later document; the value is the number of the OEP that replaces the current document. The newer OEP must have a Replaces header that contains the number of the OEP that it rendered obsolete.

  • The References header is a useful section to provide quick links to relevant materials and prior discussions regarding the proposal.

Auxiliary Files#

OEPs may include auxiliary files such as diagrams. Such files must be added to an oep-XXXX/ directory, where “XXXX” is the OEP number. Include original diagrams alongside image files, to make it easy for others to update the OEP in the future.

Change History#

For every change (including the initial document creation), include an entry in a “Change History” section modeled off the one below. A Change History entry should include three parts: the date of the change, a very brief summary of changes made, and a link to the pull request where the discussion and approval took place. The changes should be ordered such that the most recent change is at the top of the list.

Change History#

2022-10-05#

  • Require OEPs merged as “Draft” or “Provisional” to provide a reference for “Follow Up Work” with a link to a rollout doc, follow up PR, or similar.

  • Pull request #387

  • Pull request #391

2022-09-23#

  • Move OEP templates to a top-level directory for better discoverability

  • Pull request #382

2022-06-22#

  • Clarify how to provide a Draft or Under Review status when the OEP PR is planned to be merged with a status other than Accepted, like Provisional as an example.

2022-04-06#

  • Clarify what is currently meant by “Architecture Group” (not an official team right now)

  • Pull request #326

2022-02-27#

Multiple changes.

    • Codify the “Change History” section, which most OEPs already use

    • Specify that entries should link to the discussion PR.

    • Pull request #297

2022-01-13#

  • Codifying that choosing an Arbiter, in practice, is done by the OEP Author(s)

  • Remove authority for assiting with arbitration and the overall process from the edX internal architecture team to the Open edX community architecture group

  • Pull request #284

2020-10-01#

2019-08-27#

  • Changed announcement process from email to Discourse.

  • Minor clarifications to wording.

  • Pull request #123

2018-11-06#

2018-05-05#

  • Further simplify process

    • Reduce steps in submission process

      • Remove the obvious “scope your idea” as an initial step.

      • Remove “vet your idea” before creating a Draft.

      • Move “request an arbiter” as 1st step in place of vetting and scoping.

    • Support alternative simpler templates.

  • Refactored description for OEP status and review.

  • Pull request #60

2018-02-05#

  • Simplify process

    • Favor announcing on Slack over emailing edx-code.

    • For Best Practice OEPs, favor updating rather than replacing.

    • Reiterate option to have multiple authors to share the load.

    • Add an explicit “Review Period” so process is finite and clear.

    • Documentation readability

      • Slight rearranging of sections, with further table of contents.

      • Break down submission process in 5 clear steps.

      • Fix a few typos with State transitions.

  • Replace edX Chief Architect with Architecture Team.

  • Append type and brief title to an OEP’s file name.

  • Remove “Product Enhancement” proposal type.

  • Remove support for Google Docs for discussion.

  • Pull request #53

2016-10-11#

  • Add a new “Product Enhancement” proposal type

  • Remove references to arch@ email address.

  • Create “Initial Submission” section.

  • Increase scope of Arbiter role to include helping with GitHub and other technical mechanics as needed.

  • Add support for Google Docs and other external forums for discussion of the proposal.

  • Add “References” field to the preamble.

  • Pull request #17

2016-08-24#

  • Add a definition of the Change History section.

  • Add a copyright notice.

  • Pull request #19

2016-05-16#