Repository organization OEP planning (OEP-57, OEP-61)

Owned by Kyle McCormick
Last updated: Nov 07, 2022Version comment
4 min read

See also:

This is a living, informal planning document for OEP-57 and OEP-61. Feel free to share your feedback.

Recap

  • I first wrote an OEP-57 draft titled “Core Repositories” back in February, with the goal of shrinking the Open edX release and the openedx GitHub organization. I got a lot of interesting feedback there, but I don’t plan on moving forward with that specific draft.

  • Later, Jenna shared a Product WG charter which would task the group with creating a Product Narrative and Core Product Offering. This aligned really well with my OEP-57 thoughts. Since then:

  • Jenna has kicked off the Product WG initiative to define a Product Narrative, which inform their definition of a Core Product Offering.

  • I created a diagram describing how I think the Core Product Offering should impact named releases, repository locations, and support commitments, and shared it with the Product WG.

  • I decided to split this effort into two OEPs: one to declare what a “Product Offering” is (OEP-57), and one to define the new repository classification system in detail based on the idea of Product Offerings (OEP-61). Furthermore, a few other OEPs would need to be updated.

Plan

Create OEP-57 (Product Offerings)

Update: This is in review now!

Create OEP-61 (Repository Organization & Metadata)

This OEP would:

  • Replace OEP-2 (Repository Metadata), obsoleting the openedx.yaml files.

  • Explain that we will be using Backstage to organize our repositories via in-repo catalog-info.yaml files (drawing heavily from this OEP-55 ADR) and that Backstage will be publicly visible to the community.

  • Describe a schema for catalog-info.yaml that is a valid subset of the Backstage System Model.

    • The schema will include the attributes:

      • spec::owner (a GitHub group or user)

      • spec::lifecycle

      • spec::type

      • metadata::annotations::openedx.org/tier

    • The meanings of the lifecycle, type, and tier attributes, as well as their valid values, will be detailed in the OEP.

    • Initial value assignments for these attributes to all openedx-org repositories will be included in the OEP (via a link to a spreadsheet; the values themselves shouldn’t be baked in to the OEP).

    • The attributes are detailed and tentatively applied to the openedx org in this sheet.

  • Explain that all repositories in the Official, Core, and Kernel tiers must be in the openedx GitHub organization. Explain that other repositories should be moved out of the openedx GitHub organization. Describe a process for moving repositories in either direction.

  • Describe that the repository maintainers are expected to keep the catalog-info.yaml files up-to-date.

  • Describe that we may automatically generate parts of READMEs based on the contents of catalog-info.yaml.

Related work:

Update OEP-10 (Open edX Releases)

This update would:

  • Define new release criteria, which could be automatically calculated from the lifecycles, types, and tiers from OEP-61:

    • Should it be included?

      • Should be included by tagging the repository?

      • Or indirectly included, via package installation by a tagged repository?

    • Should it be enabled by default?

    • Should it be considered supported?

  • Remove edX-specific language that’s still lingering around.

  • Remove the old definitions of supported and included.

  • Remove references to OEP-2, whose openex.yml files were used in order to decide which branches to tag.

  • Mention that the Build-Test-Release WG is responsible for the releases.

Update OEP-14 (Archiving GitHub Repositories)

  • This update would:

    • Change:

      • When a repository under the openedx organization will no longer be maintained by the Open edX community because it is no longer in use by the latest version of the Open edX platform, the following steps should be followed. // This process is not for repositories that are currently still in use by either the latest release or the master branches of the Open edX platform. If a repository is in use, but planned to be removed, it should go through the deprecation process and when that is completed it can be archived as described by the process below.

    • To:

      • When an repository within the openedx organization whose tier is “unofficial” will no longer be maintained by the Open edX community, the communication & archival process specified below should be followed. // This process is not for repositories in the openedx organization whose tiers are “kernel”, “core”, or “official”. Those repositories must go through the deprecation process, allowing the tier to be changed to “unofficial”. When that is completed, it can be archived as described by the process below.

Update OEP-21 (Deprecation and Removal)

  • This update would:

    • add a step for changing the lifecycle to “deprecated” when a deprecation is accepted.

    • add a step for changing the tier to “unofficial” when a deprecation is completed.

In the future… Create a new OEP on Repository Naming

When I defined the type field for OEP-61, I tried to define it in a way that would mesh nicely with a hypothetical set of repository naming conventions. I’m interested in pursuing this eventually, but NOT now. Maybe in a couple years when we have a bigger change budget at our disposal. I would only want to do this if we could feel safe renaming most existing repositories.