Improve discoverability of repository and API status through declarative registry

[wrathwolf]

Problem description

It is difficult today for CAMARA participants, members, and external consumers to quickly determine the status of a given API or repository. Questions like "is this API in a Sub Project or an independent sandbox?", "what lifecycle stage is it in?", "who do I contact?", and "is this repo still active?" require cross-referencing multiple sources.

This information exists but is fragmented:

• Repository descriptions carry lifecycle labels (e.g. "Sandbox API repository for..." or "Incubating API repository for...") but these are free-text strings primarily consumed by tooling, not a structured or searchable classification
• The wiki tree implicitly encodes nesting (Sub Projects vs Independent Sandbox Repositories vs Archived Repositories) but the placement isn't always correct or kept in sync with lifecycle transitions
• config/api-landscape.yaml carries API-level enrichment (category, website, tooltip) but is keyed by API, not by repository
• config/meta-release-mappings.yaml maps repos to meta-releases but only for repos participating in a release cycle
• data/releases-master.yaml collects release data but is scoped to releases, not to overall project classification or health

The result is that there is no single place a person can look to answer "what is the current state of this repository and where does it fit in CAMARA?"

In #50, @hdamker outlined a move toward a declarative central config file with reconciliation workflows. This issue captures the discoverability requirements, so they are considered as the schema evolves.

Possible evolution

A declarative repository registry, maintained via bot PR in project-administration, that serves as the authoritative answer to "what is this repo and what's its status." The registry would be consumed by existing workflows (repo setup, wiki generation, landscape sync) but its primary purpose is to make project and API status discoverable and unambiguous for anyone in the CAMARA ecosystem.

The registry would contain two sections: a sub_projects section defining each Sub Project as a first-class entity, and a repositories section where each repo references its Sub Project by slug.

Fields that directly improve discoverability, aligning with the attributes @hdamker discussed in #50:

Sub Project fields:

• name — display name of the Sub Project
  • Connectivity Quality Management
  • Know Your Customer
  • Device Status
  • Device Location
  • Edge Cloud
  • Number Insights
  • Call Forwarding Signal
  • Population Density Data
• mailing_list — the Sub Project's mailing list, so newcomers know where to engage
  • sp-qod@lists.camaraproject.org
  • sp-kyc@lists.camaraproject.org
  • sp-dst@lists.camaraproject.org
• wiki_page — direct link to the Sub Project's canonical wiki page
  • https://lf-camaraproject.atlassian.net/wiki/x/...
• repositories — the list of repos belonging to this Sub Project, providing a single place to see the full group membership

Repository fields:

• repository type — clearly distinguishes API repositories from working group, infrastructure, and governance repos, so consumers know what they're looking at
  • api — API specification repositories (e.g. QualityOnDemand, SimSwap, DeviceLocation)
  • working-group — working group repositories (e.g. Commonalities, ReleaseManagement, IdentityAndConsentManagement)
  • infrastructure — project tooling and administration (e.g. tooling, project-administration, Template_API_Repository)
  • governance — governance documentation (e.g. Governance)
• lifecycle state (API repos, per Governance) — makes it immediately clear whether something is a sandbox, incubating, graduated, or archived, without having to interpret free-text descriptions or wiki tree placement
  • sandbox-independent — standalone sandbox not yet part of a Sub Project (e.g. ModelAsAService, NetworkSliceBooking)
  • sandbox-subproject — sandbox within an existing Sub Project (e.g. DedicatedNetworks under Connectivity Quality Management)
  • incubating — accepted into a Sub Project with at least one operator implementation (e.g. QualityOnDemand, DeviceLocation, SimSwap)
  • graduated — widely adopted stable API (none currently, criteria being defined)
  • archived — no longer actively maintained (e.g. HomeDevicesQoD, ShortMessageService, SiteToCloudVPN)
• sub_project — references the Sub Project slug this repo belongs to, linking it to the group definition above
  • connectivity-quality-management
  • know-your-customer
  • device-status
  • independent — for standalone sandbox repos not yet adopted by a Sub Project
  • null — for working group, infrastructure, and governance repos
• mailing_list — for repos with their own list distinct from the Sub Project list, or for independent sandboxes and working groups
  • wg-commonalities@lists.camaraproject.org
  • null — when the Sub Project list is sufficient
• wiki_page — direct link to the canonical wiki page for the repo
  • https://lf-camaraproject.atlassian.net/wiki/x/...
  • null — during bootstrap, before a wiki page is created

Example structure:

sub_projects:
  connectivity-quality-management:
    name: Connectivity Quality Management
    mailing_list: sp-qod@lists.camaraproject.org
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/RMuOAQ
    repositories:
      - QualityOnDemand
      - QoSBooking
      - DedicatedNetworks

  know-your-customer:
    name: Know Your Customer
    mailing_list: sp-kyc@lists.camaraproject.org
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/g8AOAQ
    repositories:
      - KnowYourCustomerMatch
      - KnowYourCustomerFill-in
      - KnowYourCustomerAgeVerification

repositories:
  QualityOnDemand:
    type: api
    lifecycle_state: incubating
    sub_project: connectivity-quality-management
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/fJkDAQ

  ModelAsAService:
    type: api
    lifecycle_state: sandbox-independent
    sub_project: independent
    mailing_list: sp-maas@lists.camaraproject.org
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/...

  Commonalities:
    type: working-group
    mailing_list: wg-commonalities@lists.camaraproject.org
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/_QPe

  HomeDevicesQoD:
    type: api
    lifecycle_state: archived
    sub_project: null
    wiki_page: https://lf-camaraproject.atlassian.net/wiki/x/...

Alternative solution

Rather than introducing a new registry file, we can combine or extend the existing data files to cover this. Each file would need to grow beyond its current scope:

config/api-landscape.yaml is currently keyed by API slug and carries enrichment data (category, website URL, tooltip, first release). It could be extended to include repository-level fields:

apis:
  quality-on-demand:
    category: Communication Quality
    website_url: https://camaraproject.org/**/
    tooltip: Allows users to set mobile connection quality and get notifications
    published: true
    first_release: PreFall24
    # New fields:
    repository: QualityOnDemand
    lifecycle_state: incubating
    sub_project: connectivity-quality-management
    mailing_list: sp-qod@lists.camaraproject.org

The limitation is that this file is keyed by API rather than by repository. A single repo hosting multiple APIs (e.g. DeviceStatus, KnowYourCustomer) would have the same repository-level fields repeated across each API entry, with no single authoritative record. Non-API repositories (working groups, infrastructure, governance) don't belong in a file named api-landscape and would need to be forced into an API-keyed structure that doesn't fit. Sub Projects as a grouping concept also have no natural home here.

config/meta-release-mappings.yaml already names repositories and maps them to release cycles. It could carry additional per-repo metadata:

mappings:
  Fall25:
    QualityOnDemand:
      release_cycle: "r3"
      # New fields:
      lifecycle_state: incubating
      sub_project: connectivity-quality-management
      mailing_list: sp-qod@lists.camaraproject.org

The limitation is that only repos participating in a meta-release appear here. New sandboxes, working group repos, archived repos, and anything between release cycles would have no entry, which defeats the discoverability goal.

data/releases-master.yaml is auto-generated by the Release Collector workflow and contains detailed release state data. Adding human-curated declarative fields here would blur the distinction between manually maintained and machine-generated fields, making it unclear which fields a human should edit and which will be overwritten during the next workflow run.

A combined approach could work by merging all three files into a single large config, but this would create a file serving three very different purposes (API enrichment, release mapping, repository classification) with three different update cadences and ownership models. A separate registry file keyed by repository name, with Sub Projects as first-class entities, avoids overloading existing schemas while staying focused and easy to maintain via PR.

Additional context

• The registry would sit alongside the existing config files and be consumed by the same workflows in camaraproject/tooling and project-administration
• API-to-repo relationships are already carried by release-metadata and release-plan (owned by ReleaseManagement), so the registry does not need to duplicate that
• Related: @hdamker's planned replacement for Update Repository Compliance Overview Workflow #50 covering the reconciliation side

Two additional items worth discussing as the schema takes shape:

1. proposal as an optional lifecycle entry. The Governance docs don't define this state today, but the APIBacklog intake process effectively creates one. APIs are raised as issues in APIBacklog, discussed by the TSC, and eventually either receive a repository or are declined. A lightweight registry entry (triggering no reconciliation until it transitions to sandbox) would make incoming proposals discoverable alongside active repos, giving the community a complete view of the pipeline.

2. LFX Insights badge as a standard README element. Rather than collecting and storing activity data, repos could include the LFX Insights Active Contributors badge. The badge URL is predictable from the repo name, so a reconciliation workflow can generate and inject it:

[![LFX Active Contributors](https://insights.linuxfoundation.org/api/badge/active-contributors?project=telcoapi&repos=https://github.com/camaraproject/{RepoName})](https://insights.linuxfoundation.org/project/telcoapi/repository/camaraproject_{reponame_lowercase}/development)

This gives anyone visiting a repo an immediate, live signal of contributor activity without putting collected data into the declarative file.