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

Build: option to skip a broken documentation artifact with a warning instead of failing

Aperta
  • Qualcosa non va?
#113 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
github-actions, javascript
Ambito
build-system, ci-cd, documentation

Direzione di ricerca

Start in scripts/build-vite.js and trace the existing registry, extraction, validation, checker, and installation flow through scripts/fetch-apps.js, scripts/artifacts.js, src/utils/registry.js, and scripts/check-artifact.js. Read .github/workflows/build-image.yml, CLAUDE.md, and contract/DEPLOYMENT.md for the requested flag and documentation surfaces. Done means isolated failures warn and skip cleanly, skipped entries are recorded, all-skipped builds fail, and existing default behavior remains unchanged with the requested hermetic tests.

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

Descrizione

Problem

One broken documentation artifact fails the whole knowledge base build. Every registry entry is all-or-nothing: if any single repo publishes a bad kb-docs.tar.gz, the deployment cannot be rebuilt at all — including for the other, perfectly healthy docs — until that repo re-publishes or someone edits the registry.

Today the only way to skip an entry is "optional": true, and that is narrow on purpose:

  • it only covers a missing prebuilt/localPath artifact (scripts/build-vite.js, the registeredApps filter);
  • it is rejected outright by KB_STRICT, i.e. in every production build.

Anything else wrong with an artifact still aborts the build, e.g.:

  • Release / asset download fails (scripts/fetch-apps.js: missing release, missing kb-docs.tar.gz, network/auth error)
  • unsafe or corrupt archive (scripts/artifacts.js: traversal, absolute path, symlink, bad gzip)
  • missing or invalid kb-docs.json (src/utils/registry.js manifest validation)
  • wrong package structure (declared app directory missing, pages pointing at files that do not exist)
  • an error finding from the contract checker (scripts/check-artifact.js) in a strict build
  • an entry that produces no apps (strict)
  • a slug that collides with another artifact's (resolveRegistry)

Proposal

Add a build parameter that turns a per-entry failure into a warning + skip instead of a build failure.

  • Flag --skip-failed / env KB_SKIP_FAILED=true on scripts/build-vite.js (name open to bikeshedding), plus a matching skip-failed input on .github/workflows/build-image.yml so a deployment repo can opt in.
  • Default off — current behaviour (fail fast) is unchanged unless asked for.
  • When on, each registry entry is staged, extracted, validated, checked and installed inside its own try/catch. On any error:
    • log a warning naming the source (owner/repo@version) and the reason;
    • remove whatever that entry already wrote to apps/{slug}/ / public/{slug}/, so no half-installed app reaches Astro;
    • leave it out of the expansion map, so the catalog and masthead navigation never link to it;
    • continue with the next entry.
  • Record skipped entries in dist/kb-build.json (e.g. skipped: [{ source, version, reason }]) and in the GitHub job summary, so a skipped doc is visible rather than silently absent.
  • The build still fails if every entry is skipped (never publish an empty knowledge base), and on errors that are not attributable to one entry (registry file unreadable/invalid, astro build itself failing, stylesheet alias step).

Open questions

  1. Interaction with KB_STRICT. Strict currently exists so that "a registered app that cannot be fetched is a broken deployment, not something to skip with a warning". Options:
    • KB_SKIP_FAILED is allowed together with strict, and strict keeps only its registry-level guarantees (no prebuilt/localPath/optional, non-empty registry), while per-artifact errors become skips; or
    • the two are mutually exclusive and the build refuses the combination.
      Leaning to the first: a production deployment is exactly where one team's broken release should not block everyone else's docs.
  2. Should a skip ever fail the job? e.g. exit 0 but set a GitHub Actions warning annotation, or an optional max-skipped threshold.
  3. Fallback to the previous good version? Out of scope here, but worth noting: instead of dropping an entry, the build could fall back to the last release that passed. Could be a follow-up.
  4. Slug collisions — skip both entries, or the later one in registry order?

Acceptance criteria

  • New flag/env/workflow input, off by default, documented in CLAUDE.md (Environment Variables), contract/DEPLOYMENT.md and build-image.yml input description.
  • With the flag on, each failure class listed above skips only the offending entry with a warning; the rest of the knowledge base builds and deploys.
  • Skipped entries appear in dist/kb-build.json and the job summary with their reason.
  • No leftover files from a skipped entry in apps/, public/ or dist/; no catalog card or nav link to it.
  • All entries skipped → build fails.
  • With the flag off, behaviour is byte-for-byte unchanged (existing suites stay green).
  • Tests: a hermetic registry with one good fixture plus one broken artifact per failure class (bad archive, missing manifest, invalid manifest, missing app dir, checker error) — build succeeds, only the good app is in dist/, kb-build.json lists the skips.
Lingua principale
JavaScript
Stelle
0
Fork
0
Merge medio
20m
PR unite (30g)
8

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 AbsaOSS/knowledge-base

Tutte le issue di AbsaOSS/knowledge-base

Issue simili

Altre issue su JavaScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.