Provisional
OEP-55 laid out that we should document the maintainers of a component.
As a maintainer it is hard to know what components you are maintaining.
As a community member it is currently difficult to quickly look up who the maintainers are for multiple components quickly.
Given the number of repos that make up the Open edX platform and the complexity of the job of maintaining them, we need a system for cataloging, and making transparent the critical details of our repositories.
To solve the above issues and to enable the potential to ease other discoverability and maintainership burdens, the Open edX community shall maintain a backstage instance and related metadata.
To support the backstage instance ownership data will have to be stored in a
structured way. We will follow Backstage best practices and store this data
in a catalog-info.yaml file in each component repository.
Once a backstage instance exists we have the opportunity to further leverage it as a centralized access point for maintainers as well as community members to quickly and easily assess different components and find relevant links to code, documentation, owners, etc.
Backstage will also give us the ability to expose other health metrics to maintainers so they can more easily assess the components they own.
As a result of adding the catalog-info.yaml file we end with two top-level
files that have very similar data. If this decision is not reversed after the
initial pilot, it may make sense to revisit this consequence and see if we can
consolidate this metadata into a single file. tcril-engineering#331 has been created
to follow up on this work.
Easy to build and get a high level view of the system.
Not a beautiful UI for maintainers to work with.
Data overload as we put more and more data into it with little to no control over the presentation of the data.
Easy to see while in the repo.
Harder to aggregate the data from the unstructured files in a way that would allow us to easily build a single pane of glass where maintainers can see all the things they own.
Backstage project site.
catalog-info.yaml spec definition
Backstage system model has detail about the different kinds of components and how they connect to each other.
Sample catalog-info.yaml file. Comments here starting with “Required”
or “Optional” shouldn’t appear in the file, they are here to help explain the
sample:
# This file records information about this repo. Its use is described in OEP-55:
# https://open-edx-proposals.readthedocs.io/en/latest/processes/oep-0055-proc-project-maintainers.html
apiVersion: backstage.io/v1alpha1
# (Required) Acceptable Values: Component, Resource, System
kind: Component
metadata:
name: 'docs.openedx.org'
description: "This repository contains the root documentation site for https://docs.openedx.org"
links:
- url: "https://docs.openedx.org"
title: "Deployed Site"
icon: "Web"
annotations:
# (Optional) Annotation keys and values can be whatever you want.
# We use it in Open edX repos to have a comma-separated list of GitHub user
# names that might be interested in changes to the architecture of this
# component.
openedx.org/arch-interest-groups: "feanil"
spec:
# (Required) This can be a group(`group:<group_name>` or a user(`user:<github_username>`)
owner: group:docs.edx.org-maintainers
# (Required) Acceptable Type Values: service, website, library
type: 'website'
# (Required) Acceptable Lifecycle Values: experimental, production, deprecated
lifecycle: 'production'
# (Optional) The value can be the name of any known component.
subcomponentOf: '<name_of_a_component>'
# (Optional) An array of different components or resources.
dependsOn:
- '<component_or_resource>'
- '<another_component_or_resource>'