Addressing PR comments by Claude · Pull Request #25 · DevExpGbb/devexpgbb.github.io

Claude · 2026-02-11T16:10:38Z

Original prompt

This section details on the original issue you should resolve

<issue_title>Introduce .gbbcatalog.yml opt-in publication model and automated catalog lifecycle sync</issue_title>
<issue_description>

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:

.gbbcatalog.yml exists in repo root
catalog.enabled: true
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

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
Catalog Sync
- If catalog.enabled: true → add/update repo in central catalog index
- If file deleted or enabled: false → remove repo from catalog
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 ...

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

- Add validation script (validate-catalog.cjs) for .gbbcatalog.yml files - Add fetch script (fetch-catalog-metadata.cjs) to retrieve catalog metadata - Create catalog-sync.yml workflow for weekly sync and stale review detection - Update refresh-data.yml to include catalog metadata fetching - Add catalog metadata display in RepoCard component (maturity, owner, state) - Update TypeScript types to include CatalogMetadata interface - Create CATALOG_SPEC.md documentation for GBB users - Add .gbbcatalog.yml.example template - Create .gbbcatalog.yml for this repository as example - Initialize empty catalog-metadata.json Co-authored-by: francescomanni <72417313+francescomanni@users.noreply.github.com>

scripts/validate-catalog.cjs

+ */
+
+const fs = require('fs');
+const path = require('path');


francescomanni · 2026-02-11T16:26:00Z

@claude[agent] this implementation is applicable just to asset type "code" (which is linked to repos) it will not impact other asset types.

francescomanni · 2026-02-11T17:24:34Z

@claude[agent] 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

Co-authored-by: francescomanni <72417313+francescomanni@users.noreply.github.com>

Claude · 2026-02-11T17:29:31Z

@claude[agent] some corrections:

for last_reviewed we can use the repo last update date. If review is needed (last update > 6 months old)
...

Done! I've implemented all three corrections:

✅ last_reviewed now uses repo last update date - The field is now optional. If not provided, the system automatically uses the repository's pushedAt (last commit push time) as the review date.
✅ Repos auto-disabled when stale - If a repository hasn't been updated in more than 6 months (or the configured review_cycle_days), it's automatically removed from the catalog by setting enabled: false.
✅ Issue creation for stale repos - The workflow still creates GitHub issues tagged with the owner when repos need review, so owners are notified to either push new commits or manually update the last_reviewed date.

Key changes:

scripts/validate-catalog.cjs: Made last_reviewed optional
scripts/fetch-catalog-metadata.cjs: Now fetches repo metadata and uses pushedAt date when last_reviewed is missing; auto-disables stale repos
CATALOG_SPEC.md: Updated documentation to reflect new behavior
Example files: Removed last_reviewed to show it's optional

Changes implemented in 1944bef.

francescomanni · 2026-02-11T17:31:03Z

@claude[agent] to avoid noise, make sure the notification is only sent to GBBs who own a repo that already contains the .gbbcatalog.yml file - ignore others from this lifecycle management.

Co-authored-by: francescomanni <72417313+francescomanni@users.noreply.github.com>

Claude · 2026-02-11T17:33:48Z

@claude[agent] to avoid noise, make sure the notification is only sent to GBBs who own a repo that already contains the .gbbcatalog.yml file - ignore others from this lifecycle management.

Done! The system now only processes and notifies owners of repositories that have opted into catalog lifecycle management by adding a .gbbcatalog.yml file.

Key changes:

Repos without .gbbcatalog.yml are completely ignored (no processing, no notifications)
Repos with .gbbcatalog.yml that become stale are included in catalog-metadata.json with state: 'needs-review' so owners can be notified
Stale repos are set to enabled: false so they don't appear in the catalog UI
Only owners who have explicitly opted in receive notifications

This avoids noise for repos that haven't joined the catalog system while ensuring proper lifecycle management for those that have.

Changes implemented in d3ecf21.

francescomanni

LGTM - I rely on @0GiS0 to understand the details

Initial plan

cea3f4c

Claude AI assigned Claude and francescomanni Feb 11, 2026

Claude started work on behalf of francescomanni February 11, 2026 16:11 View session

github-code-quality bot found potential problems Feb 11, 2026

View reviewed changes

scripts/validate-catalog.cjs

*/

const fs = require('fs');

const path = require('path');

Claude AI changed the title ~~[WIP] Introduce .gbbcatalog.yml opt-in publication model~~ Implement .gbbcatalog.yml opt-in catalog publication with automated lifecycle management Feb 11, 2026

Claude AI requested a review from francescomanni February 11, 2026 16:22

Claude finished work on behalf of francescomanni February 11, 2026 16:22

Claude started work on behalf of francescomanni February 11, 2026 16:26 View session

Claude AI changed the title ~~Implement .gbbcatalog.yml opt-in catalog publication with automated lifecycle management~~ Addressing PR comments Feb 11, 2026

Claude finished work on behalf of francescomanni February 11, 2026 16:28

francescomanni requested a review from 0GiS0 February 11, 2026 16:31

Claude started work on behalf of francescomanni February 11, 2026 17:25 View session

Make last_reviewed optional and auto-disable stale repos

1944bef

Co-authored-by: francescomanni <72417313+francescomanni@users.noreply.github.com>

Claude finished work on behalf of francescomanni February 11, 2026 17:30

Claude started work on behalf of francescomanni February 11, 2026 17:31 View session

Only notify owners of repos with .gbbcatalog.yml files

d3ecf21

Co-authored-by: francescomanni <72417313+francescomanni@users.noreply.github.com>

Claude finished work on behalf of francescomanni February 11, 2026 17:34

francescomanni marked this pull request as ready for review February 11, 2026 17:34

francescomanni approved these changes Feb 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Addressing PR comments#25

Addressing PR comments#25
Claude wants to merge 4 commits intomainfrom
claude/introduce-gbbc-catalog-yml

Claude AI commented Feb 11, 2026 •

edited

Loading

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

Claude AI commented Feb 11, 2026

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

Claude AI commented Feb 11, 2026

Uh oh!

francescomanni left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

Claude AI commented Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Objective

1. Current Challenge

2. Publishing Model

3. .gbbcatalog.yml Specification

Minimal Schema (v1)

4. Lifecycle Model

States

5. Automation Requirements

Trigger

Responsibilities

6. Non-Goals

7. GBB Guidance

8. Benefits of This Model

9. Executive Summary

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

Claude AI commented Feb 11, 2026

Uh oh!

francescomanni commented Feb 11, 2026

Uh oh!

Claude AI commented Feb 11, 2026

Uh oh!

francescomanni left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Claude AI commented Feb 11, 2026 •

edited

Loading

3. `.gbbcatalog.yml` Specification