Support repository-owned catalog metadata #28

Closed
opened 2026-11-07 21:51:25 +00:00 by martin · 8 comments
Owner

Goal

Let repositories describe themselves without indefinitely growing the central mapping in scripts/sync-forgejo-catalog.mjs.

Acceptance criteria

  • Define precedence between discovered fallback entities and repository catalog-info.yaml descriptors.
  • Described repositories appear without duplicate components, unstable identities, or broken references.
  • Pilot explicit ownership, lifecycle, systems, APIs, and links in selected repositories.
  • Correct this portal's starter self-description and document repository onboarding.
  • Validate descriptors and document fallback behavior for repositories without them.

Depends on

  • #23 — Verify the imported catalog end to end.
  • #53 — Remove the central personal-services System registration.
  • Personal/cluster#86 — Add the personal-services System to the cluster catalog descriptor.
  • Personal/recurring-events#61 — Add Backstage catalog descriptors for the service and API.
  • Personal/toolbox#64 — Add a Backstage catalog descriptor.
  • Personal/martials.no#88 — Add a Backstage catalog descriptor.
  • Coordinate with #24 — Make Forgejo discovery resilient and continuously refreshed.

Phase

2 — Useful developer workflows

## Goal Let repositories describe themselves without indefinitely growing the central mapping in `scripts/sync-forgejo-catalog.mjs`. ## Acceptance criteria - [x] Define precedence between discovered fallback entities and repository `catalog-info.yaml` descriptors. - [x] Described repositories appear without duplicate components, unstable identities, or broken references. - [x] Pilot explicit ownership, lifecycle, systems, APIs, and links in selected repositories. - [x] Correct this portal's starter self-description and document repository onboarding. - [x] Validate descriptors and document fallback behavior for repositories without them. ## Depends on - #23 — Verify the imported catalog end to end. - #53 — Remove the central personal-services System registration. - Personal/cluster#86 — Add the personal-services System to the cluster catalog descriptor. - Personal/recurring-events#61 — Add Backstage catalog descriptors for the service and API. - Personal/toolbox#64 — Add a Backstage catalog descriptor. - Personal/martials.no#88 — Add a Backstage catalog descriptor. - Coordinate with #24 — Make Forgejo discovery resilient and continuously refreshed. ## Phase 2 — Useful developer workflows
Author
Owner

Progress

  • Opened Personal/toolbox#65, Personal/martials.no#89, and Personal/recurring-events#62 for the repository-owned descriptors.
  • Backstage YAML parsing and entity schema validation passed for all descriptors; entity refs are unique and git diff --check passed.
  • All three PRs are open and unmerged. End-to-end catalog ingestion and central example reconciliation remain to be verified under this issue.
## Progress - Opened [Personal/toolbox#65](https://code.martials.no/Personal/toolbox/pulls/65), [Personal/martials.no#89](https://code.martials.no/Personal/martials.no/pulls/89), and [Personal/recurring-events#62](https://code.martials.no/Personal/recurring-events/pulls/62) for the repository-owned descriptors. - Backstage YAML parsing and entity schema validation passed for all descriptors; entity refs are unique and `git diff --check` passed. - All three PRs are open and unmerged. End-to-end catalog ingestion and central example reconciliation remain to be verified under this issue.
Author
Owner

Progress

  • Repository descriptors have merged: Personal/toolbox#65, Personal/martials.no#89, and Personal/recurring-events#62.
  • Backstage parsing/schema validation passed for all descriptors, with unique entity refs; git diff --check passed. The merged descriptors are on each repository's main branch.
  • End-to-end catalog ingestion, API rendering, central example reconciliation, and canonical ownership of the personal-services System remain to be verified. This issue remains open.
## Progress - Repository descriptors have merged: [Personal/toolbox#65](https://code.martials.no/Personal/toolbox/pulls/65), [Personal/martials.no#89](https://code.martials.no/Personal/martials.no/pulls/89), and [Personal/recurring-events#62](https://code.martials.no/Personal/recurring-events/pulls/62). - Backstage parsing/schema validation passed for all descriptors, with unique entity refs; `git diff --check` passed. The merged descriptors are on each repository's `main` branch. - End-to-end catalog ingestion, API rendering, central example reconciliation, and canonical ownership of the `personal-services` System remain to be verified. This issue remains open.
Author
Owner

Progress

  • Opened PR #56 to remove the duplicate central recurring-events API entry, improve this repository's descriptor, and document onboarding/validation.
  • bun run tsc, focused descriptor/provider tests (12 passed), frontend/backend builds, targeted Prettier, and git diff --check passed.
  • The controlled E2E run is blocked locally: CI mode reused a pre-existing port 7007 server that returned 404; an isolated Node 24 run could not load the installed Node-22-ABI better-sqlite3 binary. The existing server was left untouched.
  • The Toolbox and martials.no descriptor issues are complete and closed. This issue remains open pending PR #56, recurring-events catalog integration/API rendering under #61, and the canonical System ownership tracked by #53.
## Progress - Opened [PR #56](https://code.martials.no/Personal/backstage/pulls/56) to remove the duplicate central recurring-events API entry, improve this repository's descriptor, and document onboarding/validation. - `bun run tsc`, focused descriptor/provider tests (12 passed), frontend/backend builds, targeted Prettier, and `git diff --check` passed. - The controlled E2E run is blocked locally: CI mode reused a pre-existing port 7007 server that returned 404; an isolated Node 24 run could not load the installed Node-22-ABI `better-sqlite3` binary. The existing server was left untouched. - The Toolbox and martials.no descriptor issues are complete and closed. This issue remains open pending PR #56, recurring-events catalog integration/API rendering under #61, and the canonical System ownership tracked by #53.
Author
Owner

Progress

  • PR #56 merged as 86487c2fe5e2318710f0d16a7665e0b1cbb64a10. The central recurring-events API registration is removed, and this repository's descriptor, onboarding documentation, and descriptor test are on main.
  • Updated the acceptance checklist for the precedence policy, repository metadata pilots, portal descriptor/documentation, and descriptor/fallback validation.
  • The remaining duplicate/reference criterion and native dependencies #53 and Personal/recurring-events#61 remain open. E2E/API rendering could not be verified locally due to the existing port-7007 server and the Node/SQLite ABI mismatch.
## Progress - [PR #56](https://code.martials.no/Personal/backstage/pulls/56) merged as `86487c2fe5e2318710f0d16a7665e0b1cbb64a10`. The central recurring-events API registration is removed, and this repository's descriptor, onboarding documentation, and descriptor test are on `main`. - Updated the acceptance checklist for the precedence policy, repository metadata pilots, portal descriptor/documentation, and descriptor/fallback validation. - The remaining duplicate/reference criterion and native dependencies #53 and Personal/recurring-events#61 remain open. E2E/API rendering could not be verified locally due to the existing port-7007 server and the Node/SQLite ABI mismatch.
Author
Owner

Progress

  • Live verification against the public Forgejo descriptors passed in an isolated Backstage run: Toolbox, martials.no, recurring-events, the recurring-events API, and personal-services each appeared once; ownership, lifecycle, links, System membership, the API definition, and the Component/API relation resolved.
  • The controlled fixture E2E suite passed all 5 tests.
  • The personal-services descriptor is now correctly assigned to Personal/cluster#86; its PR #87 is open. #28 remains open pending that PR and the central System cleanup in #53.
## Progress - Live verification against the public Forgejo descriptors passed in an isolated Backstage run: Toolbox, martials.no, recurring-events, the recurring-events API, and personal-services each appeared once; ownership, lifecycle, links, System membership, the API definition, and the Component/API relation resolved. - The controlled fixture E2E suite passed all 5 tests. - The `personal-services` descriptor is now correctly assigned to Personal/cluster#86; its PR #87 is open. #28 remains open pending that PR and the central System cleanup in #53.
Author
Owner

Progress

  • Opened cluster PR #87 for the canonical personal-services System descriptor and Backstage PR #57 for the dependent central-source cleanup. Merge #87 before #57.
  • Live Forgejo catalog verification passed for all three Components, the recurring-events API, and the current System source; the API definition/relations resolved without duplicate refs. The controlled E2E suite passed 5/5.
  • #28 remains open until both PRs merge and the live catalog is verified with the System sourced from Personal/cluster.
## Progress - Opened [cluster PR #87](https://code.martials.no/Personal/cluster/pulls/87) for the canonical `personal-services` System descriptor and [Backstage PR #57](https://code.martials.no/Personal/backstage/pulls/57) for the dependent central-source cleanup. Merge #87 before #57. - Live Forgejo catalog verification passed for all three Components, the recurring-events API, and the current System source; the API definition/relations resolved without duplicate refs. The controlled E2E suite passed 5/5. - #28 remains open until both PRs merge and the live catalog is verified with the System sourced from `Personal/cluster`.
Author
Owner

Progress

  • Personal/cluster#86 and recurring-events#61 are complete. The live catalog check confirmed the three Components, API, and System each appear once; the OpenAPI definition, ownership, system membership, and API relation resolve. The controlled E2E suite passed 5/5.
  • Backstage PR #57 removes the central System definition. Live verification against its branch passed after cluster PR #87 merged.
  • #28 remains open until PR #57 merges and the no-duplicate result is verified on main.
## Progress - Personal/cluster#86 and recurring-events#61 are complete. The live catalog check confirmed the three Components, API, and System each appear once; the OpenAPI definition, ownership, system membership, and API relation resolve. The controlled E2E suite passed 5/5. - [Backstage PR #57](https://code.martials.no/Personal/backstage/pulls/57) removes the central System definition. Live verification against its branch passed after cluster PR #87 merged. - #28 remains open until PR #57 merges and the no-duplicate result is verified on `main`.
Author
Owner

Completed. The repository-owned descriptors are merged in Personal/toolbox#65, Personal/martials.no#89, Personal/recurring-events#62, and Personal/cluster#87. Backstage source reconciliation merged in PRs #56 and #57.

Post-merge live verification on main confirmed each pilot Component, the API, and the personal-services System appears once; owner/lifecycle/link and System references resolve; the OpenAPI definition and Component/API relation load correctly. The controlled E2E suite passed all 5 tests, and the focused descriptor/provider tests passed (12 tests). All acceptance criteria and prerequisites are complete.

Completed. The repository-owned descriptors are merged in Personal/toolbox#65, Personal/martials.no#89, Personal/recurring-events#62, and Personal/cluster#87. Backstage source reconciliation merged in PRs #56 and #57. Post-merge live verification on `main` confirmed each pilot Component, the API, and the `personal-services` System appears once; owner/lifecycle/link and System references resolve; the OpenAPI definition and Component/API relation load correctly. The controlled E2E suite passed all 5 tests, and the focused descriptor/provider tests passed (12 tests). All acceptance criteria and prerequisites are complete.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
Personal/backstage#28
No description provided.