|Title||OEP Purpose and Guidelines|
|Authors||Calen Pennington <firstname.lastname@example.org>, Joel Barciauskas <email@example.com>, Nimisha Asthagiri <firstname.lastname@example.org>|
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.
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).
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.
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.
The OEP is under discussion and being reviewed by the Open edX community, the Arbiter, and the Authors.
The Arbiter has accepted the OEP after review and discussion within the agreed upon review period.
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”.
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.
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.
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.
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”.
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.
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.
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.
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.
The following updates warrant replacement OEPs.
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.
OEPs are UTF-8 encoded text files that use the reStructuredText format. ReStructuredText  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.
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:
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.
|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>|
|References||<links to any other relevant discussions or relevant related materials>|
The OEP header is a unique identifier for the OEP, consisting of
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 <email@example.com> 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.