Introduce .gbbcatalog.yml opt-in publication model and automated catalog lifecycle sync

[francescomanni]

PR Objective

The goal of the IP catalog is to provide a structured, automation-driven, and reusable way to manage our Intellectual Properties (IPs) across GitHub repos.

Current issues:

• Repos are created and left without governance.
• Field cannot easily identify “best-in-class” solutions.
• IPs can decay or become outdated.
• Existing topic/visibility-based workflows are unreliable and error-prone.

This catalog specification introduces:

• Explicit opt-in for catalog inclusion.
• Cross-org reusable configuration.
• Automation for validation, stale detection, and catalog syncing.
• Clear ownership and lifecycle management.

---

1. Current Challenge

Today:

• GBBs use a GitHub org (DevExpGBB) for IPs.
• Some repos are private (team-only), some public (OSS-ready).
• Inclusion in any catalog is ad hoc.
• Visibility or topics are sometimes used as signals but are not reliable:
  • People may make repos public for testing, even if not ready.
  • Topic names can be inconsistent or typed incorrectly.
  • Lifecycle is not tracked.

We need a system that is:

• Foolproof
• Non-invasive
• Explicit
• Automated
• Separate from visibility or experimentation

---

2. Publishing Model

A repository appears in the catalog only if:

1. .gbbcatalog.yml exists in repo root
2. catalog.enabled: true
3. Metadata validation passes

Visibility (Private / Internal / Public) does not determine catalog inclusion.
Repos in WIP, under review, or public experimentation do not automatically appear in the catalog.

---

3. .gbbcatalog.yml Specification

Location: / .gbbcatalog.yml

Minimal Schema (v1)

schema_version: 1

catalog:
enabled: true # Required: true = include, false = exclude
owner: francesco.manni # Required: GitHub handle
display_name: "IP Name" # Required: human-friendly title
description: "Short summary" # Required: 1–3 sentences
maturity: incubating # Required: incubating | production | deprecated
last_reviewed: 2026-02-10 # Required: YYYY-MM-DD
review_cycle_days: 180 # Optional: default 180 days

4. Lifecycle Model

Catalog lifecycle is independent of repository visibility.

States

Condition	Catalog State
No .gbbcatalog.yml	Not in catalog
enabled: false	Not in catalog
enabled: true	Published / Ready
enabled: true + stale review (older than review_cycle_days)	Needs Review
maturity: deprecated	Deprecated

5. Automation Requirements

A GitHub Action ensures catalog integrity and lifecycle management automatically.

Trigger

• Push to .gbbcatalog.yml
• Scheduled weekly run
• Manual workflow_dispatch

Responsibilities

1. Validation

   • .gbbcatalog.yml must exist
   • Required fields present: enabled, owner, display_name, description, last_reviewed
   • enabled must be boolean
   • maturity must be one of incubating, production, deprecated
   • last_reviewed must be a valid date
   • If invalid, fail workflow and open issue tagging owner

2. Catalog Sync

   • If catalog.enabled: true → add/update repo in central catalog index
   • If file deleted or enabled: false → remove repo from catalog

3. Stale Review

   • If today - last_reviewed > review_cycle_days
     • Mark repo as “Needs Review” in catalog
     • Open issue tagging owner requesting metadata update
   • Workflow does not auto-remove repo

6. Non-Goals

• Do not change repository visibility
• Do not rely on repository topics for lifecycle
• Do not enforce lifecycle via labels
• Do not auto-archive repositories
• Repo mutation limited to:
  • Opening issues
  • Updating central catalog index

7. GBB Guidance

• Create IPs normally with the appropriate visibility for experiments
• To publish in catalog:
  • Add .gbbcatalog.yml with enabled: true
  • Populate required metadata
• Review cycle handled automatically via workflow
• For deprecation: set maturity: deprecated in .gbbcatalog.yml
• Optional workflow enhancement: “Submit to Catalog” button that generates .gbbcatalog.yml and opens PR for review

8. Benefits of This Model

• Foolproof: no accidental catalog inclusion
• Explicit ownership per IP
• Separation of experimentation vs. catalog publishing
• Automation enforces consistency
• Detects stale IPs to prevent decay
• Reusable across multiple orgs and repos
• Scalable enterprise governance with minimal friction

9. Executive Summary

This model ensures:

• Field sees curated, up-to-date solutions
• GBBs can track and contribute safely to other IPs
• Automation manages validation, review, and catalog maintenance
• Clear lifecycle: WIP → Ready → Needs Review → Deprecated
• Separation of concerns: access control, catalog inclusion, experimentation
• Cross-org and reusable governance pattern
• Sustainable innovation and discoverable best-in-class IPs

In short: explicit opt-in via .gbbcatalog.yml ensures quality, discoverability, and sustainable innovation.

[francescomanni]

@claude some corrections:

for last_reviewed we can use the repo last update date. If review is needed (last update > 6 months old)
Mark repo as “Needs Review” in catalog and enabled false - it needs to be removed
Open issue tagging owner requesting metadata update