|Authors||Calen Pennington, Feanil Patel, Nimisha Asthagiri|
|Arbiter||Calen Pennington <firstname.lastname@example.org>|
Proposes a standard format for repository metadata for Open edX projects.
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.
Each repo will include a file
openedx.yaml, with the following keys:
owner: dictionary (optional)
This key contains information about the assigned owner of this repository.
type: string (optional)
The value of this key must be either
repo. It indicates which ownership model applies to this repository, and therefore which of these two keys should exist with a non-empty value.
Note: As much as possible, repos should be owned by higher-level repos, with only the highest-level repos owned by teams.
team: string (optional)
edx/arch-bom). If this value is set, this repository contains high-level, business-aligned functionality that is suitable for direct ownership designation to an individual responsible team.
repo: string (optional)
edx/XBlock). If this value is set, this repository contains lower-level technical functionality that is affiliated with another primary owning higher-level repository.
nick: string (optional)
tags: list of strings (optional)
oeps: dictionary (optional)
A list of keys corresponding to Best Practice OEPs (in the format
oep-n). Each value would be one of
False, or a reason dictionary.
False indicate compliance (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
reasonvalue must be included that explains why.
reasoncan optionally provide more information. The
reasonvalue will be displayed in reporting tools. If an OEP isn’t listed in the
oepsdictionary, then it is assumed to be
False, unless the reporting tool can auto-detect accordance.
openedx-release: defined by OEP-10 (optional)
archived: boolean (optional)
True, this specifies that this repository is archived and no longer maintained by edX.
supporting_teams: list of strings
ownerdictionary. As a reasonable migration of this key, set
owner.valueto the first value in
supporting_teams, and then remove
While the responsibilities of an owner are outside the scope of this OEP, a repository’s metadata should provide sufficient information to identify and discover the repository’s owner.
Rather than designating human owners to each and every repository, we designate owners to only high-level and business-aligned repositories as described in
owner.team in Keys. All other repositories are indirectly owned by owners of the high-level repositories. This indirect relationship is described in the
owner.repo designation in Keys. See Ownership Rationale.
For example, in the edx-platform repo, the file might look like:
# openedx.yaml --- owner: type: team team: edx/arch-bom 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
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:
Keeping the granularity of code ownership to high-level repositories affords us:
Keeping the granularity of human owners to individual teams affords us:
archivedand relax the requirement for an owner if
applicablekey in the reason dictionary.
nickkeys in the