OEP-1: OEP Purpose and Guidelines¶

OEP Roles¶

Each OEP must have a 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.

Each OEP also has an Arbiter (as described in Initial Submission). The Arbiter will be chosen by the edX Chief Architect (currently Eddie Fagin). The Author of an OEP will never be selected as 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 Author move the proposal through the OEP process, providing technical and process expertise as needed. The Arbiter also assists the Author to solicit feedback from the community on the OEP, and for helping to move the OEP towards a final decision (whether that decision is Accepted, Rejected, or Deferred). The Arbiter (in discussion with the Author) 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 Author has become unresponsive (as described in Transferring OEP Ownership).

Before Submitting an OEP¶

The OEP process begins with a new idea for Open edX. It is highly recommended that a single OEP contain a single key proposal or new idea. Small enhancements or patches often don’t need an OEP and can be injected into the Open edX development workflow with a patch submission.

The OEP Author should first attempt to ascertain whether the idea is appropriate for an OEP. Posting to the edx-code mailing list is the best way to go about this.

Vetting an idea publicly before going as far as writing an OEP is meant to save the potential author time. Many ideas have been brought forward for changing Open edX that have been rejected for various reasons. Asking the Open edX 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 is not always sufficient). 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 Open edX installations.

Initial Submission¶

Once the Author has asked the Open edX community whether an idea has any chance of acceptance, a draft OEP should be submitted as a pull request against the central OEP repository. To identify the draft proposal, the Author should check the numbered list of previous OEP pull requests and select the next available number. The pull request title must start with “OEP-XXX”, which claims that OEP number for the included proposal.

After the Author drafts an OEP in a format in which they are comfortable, they will request an Arbiter from the edX Chief Architect. This Arbiter will be recorded in the “Arbiter” header on the OEP. The rest of Open edX community will be given the opportunity to comment on the OEP, with the Arbiter serving to keep the discussion on track and to evaluate when it has reached a final conclusion.

For an OEP to be accepted by the Arbiter, 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 pass the existing Open edX Contribution Guidelines.

As updates are necessary, the OEP Author or Arbiter can update the pull request.

OEPs can reference pull requests to other Open edX repositories which will act as reference implementations.

OEP Review & Resolution¶

Once an OEP has been accepted by an Arbiter, it is “Under Review”. Once this state is acheived, we recommend announcing the OEP to the community in relevant forums such as the edx-code and more relevant mailing lists, the #open-edx-proposals Slack channel, and any other relevant Slack channels. It should also be added to the list of “Under Review” OEPs in the OEP repo.

A Draft OEP can be assigned the status “Deferred”. The OEP Author or Arbiter can assign the OEP this status when no progress is being made on the OEP. If an OEP is deferred, the OEP Author can reassign it to Draft status.

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. The “Withdrawn” status is similar: it means that the OEP Author themselves has decided that the OEP is actually a bad idea, or has accepted that a competing proposal is a better alternative.

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 relevant post in the edx-code mailing list archive or to the appropriate section of the PR, and the Last-Modified header should be set to the current date.

OEPs can also be superseded by a different OEP, rendering the original obsolete.

The possible paths of the status of OEPs are as follows.

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 “Draft” 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 “Draft” OEP, until it converges to being either “Accepted” or “Rejected”.

OEP Maintenance¶

In general, OEPs are not modified after they have reached the Final state. They can be replaced by subsequent OEPs, however (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 Chief Architect 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 the choice of technology in a Best Practice OEP (such as which test-runner should be used).
• 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).

OEP Formats and Templates¶

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. An OEP template can be found in the repo.

OEPs may be discussed in a more convenient format, such as a Google Doc, if it is deemed appropriate for the audience and sufficiently open to comment and review. The final OEP must be transcribed into the reStructuredText-based template and committed to the OEP repository. The Arbiter shall be responsible for ensuring the proper transcription. The reviewed and accepted OEP must reference the location of relevant discussion, and the ownership of the discussion document should be transferred to the edX Chief Architect, if applicable.

OEP Header Preamble¶

Each OEP must begin with an 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.

The Author header lists the names, and optionally the email addresses, of all the authors/owners of the OEP. The format of the Author 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.

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.

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.

Reporting OEP Bugs, or Submitting OEP Updates¶

While a pull request that contains the initial draft of an OEP 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.

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

Transferring OEP Ownership¶

It occasionally becomes necessary to transfer ownership of OEPs to a new Author. In general, it is preferable to retain the original Author as a co- author of the transferred OEP, but that is 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 OEP process, or has fallen off the face of the ‘net (that is, unreachable or not responding to email).
• A bad reason to transfer ownership is because the Author does 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 Author can always submit a separate OEP with an alternative proposal.

2016-08-24¶

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