Hacktoberfest 2026: die Issues, die Maintainer für den Oktober markiert haben – offen und einsteigerfreundlich. Hacktoberfest-Issues durchsuchen

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

Offen
  • Stimmt etwas nicht?
#113 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Anfängerfreundlichkeit
35/100
Issue-Typ
Feature
Klarheit
Größtenteils klar
Aktivitätsstatus
Aktiv
Tech-Stack
github-actions, javascript
Bereich
build-system, ci-cd, documentation

Rechercherichtung

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.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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.
Vorherrschende Sprache
JavaScript
Sterne
0
Forks
0
Ø Merge
20 Min.
Gemergte PRs (30 T.)
8

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus AbsaOSS/knowledge-base

Alle Issues in AbsaOSS/knowledge-base

Ähnliche Issues

Weitere Issues zu JavaScript

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.