docs: Add an ADR for using Backstage to support OEP-55

[feanil]

Since this is the first ADR under oep-55 I also added the relevant
directory structure and wired it up into the OEP rst.

[e0d]

Looks good.

[kdmccormick]

A couple comments on the specifics, but the overall proposal sounds great to me and I'm excited to try out Backstage 🎉

[kdmccormick]

The name, description, and source code URL as strike me as redundant with the repository's name, GitHub description, and GitHub URL. Is there anything we can do to de-dupe this or lint to keep it in sync?

[hurtstotouchfire]

maybe it could be baked into logic for the templates we start from when making new files?

See also, placeholders in yaml: https://stackoverflow.com/questions/41620674/use-placeholders-in-yaml

[feanil]

This was a bad example I think from when I was experimenting with the contents of the files. I'll update it to a link to the deployed site which might be a better example.

[robrap]

Looking forward to the new tools.

[robrap]

1. 2U/edX were maintaining much of this information in a spreadsheet before the tCRIL-split. This ADR could acknowledge the need to update this existing tooling. Even if not mentioned in the ADR, this work needs to be communicated and planned for.
2. The existing spreadsheet also has exceptional maintenance requirements for the edx-platform monolith. Does tCRIL plan on supporting that level of detail, or is it planning on having edx-platform maintained by 2U/edX, with the split ownership being decided/documented/maintained by 2U/edX as we see fit?

[feanil]

2U/edX were maintaining much of this information in a spreadsheet before the tCRIL-split. This ADR could acknowledge the need to update this existing tooling. Even if not mentioned in the ADR, this work needs to be communicated and planned for.

That feels like a consequence internal to 2U and not one for the open source project. I agree the work needs to be done either way, but I'm not sure mentioning it here is valuable from the open source project perspective.

The existing spreadsheet also has exceptional maintenance requirements for the edx-platform monolith. Does tCRIL plan on supporting that level of detail, or is it planning on having edx-platform maintained by 2U/edX, with the split ownership being decided/documented/maintained by 2U/edX as we see fit?

I think edx-platform maintainership is being avoided for the pilot but we will eventually need to make a plan for it. Given its complexity, I expect there will be a future ADR that addresses its ownership specifically.

[hurtstotouchfire]

@robrap maybe we can touch base over slack about the nature of the maintenance requirements? I'm curious how much of it would be relevant to any organization maintaining edx-platform vs 2U specifically.

[nedbat]

Where do we find the explanation of what "annotations" means? Same for "spec", etc. Is this defined by Backstage?

[feanil]

You can find it here, I linked to it from just above this code-block in the references section. Let me know if you think I need more specific stuff within the code.

[nedbat]

Sorry, I see the backstage docs now, but I have a feeling that the pure generality of their docs could be narrowed with some specifics for our use of it.

[feanil]

I'll add another comment here, let's see if that will help. Happy to add a lot more text here to help people understand what's up.

[feanil]

@nedbat does this address your concerns and provide sufficient context or would you like more words?

[nedbat]

How does "type" relate to "kind"?

[feanil]

More details on the system model are here: https://backstage.io/docs/features/software-catalog/system-model

I'll add it as a reference link.

[pomegranited]

We'd also need to update process to ensure new CCs are added to the relevant catalog-info.yaml files. Or better yet, make that part of the CC's onboarding via an OSPR.

[feanil]

@pomegranited would this not be covered by the process to elect and assign maintainers generally?

[hurtstotouchfire]

Were there no alternatives? If there are no comparable OOTB options we could perhaps note briefly why we don't want to build it ourselves out of scripts and spreadsheets, for instance

[feanil]

@hurtstotouchfire do you mean were there no alternatives services or out of box tools? If so, there are a few commercial products but their use case tends to be different. They are oriented towards protecting the content rather than making it visible to everyone so often their pricing models and workflows don't make sense for an opensource project. This felt a bit outside of the requirements of what we were looking for so I did not initially mention it since they were not viable alternatives for the basic requirement of everyone needs to be able to see it.

[hurtstotouchfire]

For some reason I have in my memory something about using github repo tags for this? I think it was @ormsbee's idea. In any case, would we want to integrate that with Backstage somehow or are they just separate concerns?

[feanil]

I don't fully understand what you're saying here but feel free to suggest text that you'd like here or another rejected alternative that you would want to document.

[kdmccormick]

Your memory serves you right @hurtstotouchfire -- on the OEP-57 draft, Dave mentioned using GH topics to group repositories into tiers like Core, Supporting, etc. Repo topics are an interesting way of storing metadata in a GH-native way that you might consider employing as you iterate on this @feanil .

Correct me if I'm wrong, but I get the sense that you are hoping to get this ADR over the line so that we can experiment with actually using backstage for the maintainer pilot. After we use backstage for a while it'll probably be easier to tell which GH features we do and don't want to tie in with, as well as what exactly the schema should look like. That is to say: I'm fine if you're not explicitly rejecting any alternatives at the moment, since we're not exactly sure what this thing will look like and how everyone will use it.

[kdmccormick]

LGTM, although I share @nedbat 's question on Type vs Kind

Consider merging as "Provisional" instead of "Accepted" as it seems like you're hoping to try to this out on a handful of repos and iterate on the spec.

[feanil]

Thanks for all the feedback everyone. I'll be merging this in as provisional shortly. If you have other concerns or feel there should be more items covered, feel free to open issues or PRs with the relevant info and I'm happy to address it.