OEP-1: OEP Purpose and Guidelines

OEP OEP-1
Title OEP Purpose and Guidelines
Last-Modified 2018-05-02
Authors Calen Pennington <cale@edx.org>, Joel Barciauskas <joel@edx.org>, Nimisha Asthagiri <nimisha@edx.org>
Arbiter
Status Accepted
Type Process
Created 2016-03-26
Review Period
Resolution open-edx-proposals#1 resolution
References

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.

Arbiter

Each OEP also has an Arbiter (as described in Step 1. Request an Arbiter). The Arbiter will be chosen by the edX Architecture Team. An Author of an OEP cannot concurrently be the Arbiter of that OEP.

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.

Finally, the Arbiter is responsible for the decision to transfer an OEP if the original Authors have become unresponsive (as described in Transferring OEP Ownership).

Architecture Team

The edX Architecture Team is accountable for assigning Arbiters to incoming Draft OEPs and revived OEPs that need a new Arbiter (if the original Arbiter is no longer available). The team can also be a resource to help or advise the Arbiter with the OEP process.

OEP Workflow

Submitting an OEP

Step 1. Request an Arbiter

Request an Arbiter from the edX Architecture Team by emailing arch-team@edx.org. 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 OEP has been accepted by an Arbiter, establish begin and end review dates with your Arbiter, making it officially “Under Review”. Once this state is achieved, we recommend announcing the OEP to the community in the following channels:

The rest of 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 or Deferred, from Deferred back to Draft, and from Under Review to Accepted, Rejected, or Withdrawn. From Accepted, the next status is Final. A Final OEP can be Replaced.

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

An OEP can be assigned the status “Deferred” when no further progress is made on the OEP. If an OEP is deferred, the OEP Authors can change it back to “Under Review”.

Rejected

An OEP can also be “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 actually a bad idea, or have accepted 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.

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” status 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”.

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.

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 OEPs

A Best Practice OEP may be updated even after it is “Accepted” as it evolves over time. A pull request should be created to update the OEP and have it go through the Step 3. Review with Arbiter process. These future edits/updates may be made by the original Authors of the OEP or by new Authors. The Arbiter may remain the same as before or may be reassigned by the edX Architecture Team.

Updating Architecture and Process OEPs

Architecture and Process 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 is up to the Arbiter of the original OEP, or the edX Architecture Team if that Arbiter is no longer available. 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 Arbiter 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.

Transferring OEP Ownership

It occasionally becomes necessary to transfer ownership of OEPs to new Authors. In general, it is preferable to retain the original Authors as co- authors of the transferred OEP, but that is really up to the original Authors.

  • A good reason to transfer ownership is because the original Authors no longer have the time or interest in updating it or following through with the OEP process, or have fallen off the face of the ‘net (that is, unreachable or not responding to email).
  • A bad reason to transfer ownership is because the Authors do not agree with the direction of the OEP. A significant aim of the OEP process is to try to build consensus around an OEP, but if that is not possible, the Authors can always submit a separate OEP with an alternative proposal.

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>
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 specifes 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.

Change History

2016-08-24

  • Add a definition of the Change History section.
  • Add a copyright notice.

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.

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.

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.