Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

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

Aberta
  • Algo errado?
#113 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
5/5
Tempo estimado
Mais de uma semana
Facilidade para iniciantes
35/100
Tipo de issue
Funcionalidade
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
github-actions, javascript
Domínio
build-system, ci-cd, documentation

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.
Linguagem predominante
JavaScript
Estrelas
0
Forks
0
Merge médio
20min
PRs com merge (30d)
8

Preparar o ambiente

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de AbsaOSS/knowledge-base

Todas as issues de AbsaOSS/knowledge-base

Issues semelhantes

Mais issues de JavaScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.