OEP-2: Repository Metadata¶

Abstract¶

Proposes a standard format for repository metadata for Open edX projects.

Motivation¶

One of the primary goals for Best Practice OEPs is to standardize techniques and tools across Open edX repositories. However, without tooling, it will be difficult to move all of the repositories in the same direction (and hard to validate which ones have been updated). This OEP exists to fill that gap. By providing a standard format for metadata about accordance to Best Practice OEPs, tools can be developed in the future to report on the current status of all of the Open edX repositories, and how well they follow the Best Practices listed in the OEPs.

Bear in mind that particular classes of Open edX repositories may have different Best Practices. The practices that apply to an XBlock may not be the same as those that apply to a standalone Django service or to a Django app.

Specification¶

Each repo in the Open edX system will include a file openedx.yaml, with the following fields:

owner: string (required unless archived is True)

The github user/team responsible for the repository.

nick: string (optional)

A short-name for the repository used by reporting tools created by the edX Open Source team. Should be 3-4 characters, because this value is used in charts with very limited space on their axes.

tags: list of strings (optional)

Used to group repositories by in reporting tools. Sample tags: core, mobile analytics.

oeps: dictionary (optional)

A list of keys corresponding to Best Practice OEPs (in the format oep-n). Each value would be one of True, False, or a reason dictionary. True and False would indicate accordance (or lack thereof) with the specified OEP. A reason dictionary provides more detailed information. It can contain a boolean state, a boolean applicable, and a string reason. If the OEP is not applicable to this repository, the reason dictionary can simply contain a single value of False for the applicable key. A False value for applicable indicates the OEP will never be applicable to this repository. For example: an OEP that defines a best practices for Javascript testing would be marked as not applicable in a python command line tool’s repository. If the state is False a reason value must be included that explains why. If the state is True or applicable is False the reason can optionally provide more information. The reason value will be displayed in reporting tools. If an OEP isn’t listed in the oeps dictionary, then it is assumed to be False, unless the reporting tool can auto-detect accordance.

track-pulls: boolean (optional)

Whether or not this repository should be tracked for creation of OSPR tickets.

openedx-release: defined by OEP-10.

archived: boolean (optional)

If True, this specifies that this repository is archived and no longer maintained by edX.

For example, in the edx-platform repo, the file might look like:

# openedx.yaml

---
owner: edx/teaching-and-learning
nick: edx
tags:
    - core
    - xblock
    - lms
    - studio
oeps:
    oep-314: True  # edx-platform uses django 3.14
    oep-42:
        state: False
        reason: This OEP doesn't actually exist
    oep-2:
        state: True  # no reason is required since this is True
    oep-100:
        applicable: False  # state is not required since the OEP is not applicable
        reason: This OEP contains best practices for C++ which is not used in edx-platform
    oep-101:
        applicable: False  # reason is not required since it's almost always just a redundant statement about it not being applicable

Rationale¶

The keys in openedx.yaml were derived from existing repository metadata collected by edx.org.

The design of the oeps dictionary was guided by a couple of use cases:

1. Adding a new OEP that few repositories will support, initially. We shouldn’t need to update all repositories to detect if they are in accordance, we should be able to assume that they aren’t, or automatically detect whether they are.
2. Repositories may have specific requirements that force them to not implement a best practice. The tools should be able to present that reasoning to anyone looking across repositories, and the reasons should be documented in the repositories themselves.
3. As much as possible, Best Practices should be autodetected, but because they will often involve a judgement call, autodetection shouldn’t be mandatory.

Change History¶