Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Populate empty AGENTS.md sections with RHDH domain context and CLI patterns

Chiusa Adatta ai principianti
  • Qualcosa non va?
#199 5 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
78/100
Tipo di issue
Documentazione
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
cli, developer-experience, documentation

Direzione di ricerca

Inizia da AGENTS.md e poi leggi gli entry point referenziati: src/lib/rhdhVersion.ts, src/commands/check-versions/command.ts e src/lib/rhdhVersion.test.ts. Compila Key Conventions, Architecture e Pattern References con la mappatura delle versioni RHDH specificata, il comportamento offline, la struttura del comando, il caching e i pattern di test; il lavoro è completo quando tutte e tre le sezioni contengono contesto operativo sul progetto.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation ready-for-triage ready-to-code

What happened

On PR #176, human reviewer PatAKnight caught 5 design-level concerns about RHDH version resolution semantics, air-gap behavior, and CLI UX that the review agent missed entirely. The agent's successful review ($8.81, opus) produced only code-level findings — valid but lower-impact. The repo's AGENTS.md has empty ## Key Conventions, ## Architecture, and ## Pattern References sections (only HTML comment placeholders), leaving the review agent with no domain context about RHDH releases, Backstage version mapping, the CLI command structure, or air-gapped deployment requirements.

Specific human findings the agent missed:

  1. Falling back to main when a release branch doesn't exist could silently resolve the wrong Backstage version
  2. RHDH_OFFLINE only skips GitHub metadata — the Backstage manifest still fetches from versions.backstage.io, so this is not air-gapped
  3. Unprefixed versions like 1.54.0 are silently treated as Backstage versions, which is easy to misread as RHDH
  4. The static compatibility matrix will require manual updates every release cycle
  5. backstage:^ peer dependencies should show an explicit unverifiable message rather than silently flagging as invalid

What could go better

The review agent had no way to reason about domain-specific design trade-offs because the AGENTS.md provides only build/test commands and PR conventions — zero architectural context. The human reviewer's design-level comments required understanding: (1) RHDH release branches and their relationship to Backstage versions, (2) the distinction between offline metadata lookup and air-gapped manifest resolution, (3) version input disambiguation (RHDH vs Backstage), and (4) static compatibility matrix maintenance burden.

High confidence that populating these sections would improve agent review depth for feature PRs touching version resolution or CLI commands. Moderate confidence for other PR types — the agent may still miss nuances requiring deep product knowledge, but having architectural context establishes a baseline the agent currently lacks entirely.

Proposed change

Fill in the three empty AGENTS.md sections:

Key Conventions: Document the RHDH-to-Backstage version mapping model (release branches, static matrix fallback, backstage: prefix escape hatch), the offline vs air-gapped distinction (RHDH_OFFLINE skips GitHub metadata but not manifest fetch; --manifest-file is needed for true air-gap), and the convention that CLI commands set process.exitCode rather than calling process.exit() directly for testability.

Architecture: Document the version resolution engine (src/lib/rhdhVersion.ts) as the core abstraction — it resolves RHDH version aliases to Backstage release versions via GitHub metadata with a static matrix fallback. Document the command structure under src/commands/ (each command is a directory with command.ts exporting registration and handler). Note the manifest caching strategy (keyed by version + base URL).

Pattern References: Point to src/commands/check-versions/command.ts as the reference for new CLI commands, src/lib/rhdhVersion.ts for version resolution patterns, and src/lib/rhdhVersion.test.ts for test patterns using mocked fetch responses.

Validation criteria

On the next 3 feature PRs that touch version resolution or add a new CLI command, the review agent should surface at least one design-level finding related to RHDH domain semantics (e.g., version mapping correctness, offline/air-gap behavior, user-facing error messages) rather than only code-level syntax and style findings.

Generated by retro agent from https://github.com/redhat-developer/rhdh-cli/pull/176

Lingua principale
TypeScript
Stelle
6
Fork
15
Merge medio
2g 9h
PR unite (30g)
26

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di redhat-developer/rhdh-cli

Tutte le issue di redhat-developer/rhdh-cli

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.