Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Auto-sync docs on stacklok-enterprise-platform release

Abierto
  • ¿Algo no está bien?
#902 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Tranquilo
Stack tecnológico
github-actions, javascript, typescript, yaml
Área
ci-cd, documentation, tooling

Línea de trabajo

Empieza por .github/workflows/upstream-release-docs.yml, .github/upstream-projects.yaml y los helpers existentes en scripts/upstream-release/ para entender el flujo actual del proyecto. Después, inspecciona la skill upstream-release-docs existente y las convenciones de documentación antes de resolver las preguntas abiertas; el trabajo estará terminado cuando haya una configuración de SEP, sincronización del manifiesto, directrices de etiquetado para enterprise, comportamiento de la skill compatible con SEP, asignación de un reviewer y una ejecución en seco retroactiva exitosa.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

documentation needs-triage

Context

When `toolhive` releases, this repo's `upstream-release-docs.yml` auto-syncs:

  1. Renovate watches `.github/upstream-projects.yaml` → opens a version-bump PR on a new toolhive tag
  2. The workflow fires on PR open, shallow-clones toolhive at the new tag, extracts release assets, runs the `upstream-release-docs` Claude skill to write narrative changes, then a `docs-review` pass for polish

We want the same flow for `stacklok-enterprise-platform` (SEP) releases, with one twist: enterprise docs are intermixed with OSS docs. The "enterprise manager" gets its own enterprise-only section, but most enterprise content is inline on OSS pages using an enterprise tag/admonition. The skill needs to know when to inline-tag vs. when to add a standalone enterprise-only page.

The companion SEP-side work (publishing release manifests) is tracked in stacklok/stacklok-enterprise-platform#1294.

Design choice: extend, don't fork

`upstream-release-docs.yml` should become project-aware rather than being cloned into `enterprise-release-docs.yml`. Reasons:

  • Enterprise content lives in the same files as OSS content — two workflows touching the same paths would race
  • 80% of the workflow (asset sync, skill invocation, reviewer assignment, PR augmentation) is identical
  • Project-specific logic (CRD extraction for toolhive, manifest parsing for SEP) is already factored into helper scripts under `scripts/upstream-release/`

Proposed work

1. Onboard SEP into `.github/upstream-projects.yaml`

Add an entry pointing at `stacklok/stacklok-enterprise-platform` with:

  • The release assets to sync (`component-versions.yaml`, `enterprise-features.yaml`, `vex.json` — see stacklok/stacklok-enterprise-platform#1294)
  • `docs_paths` hints scoped to enterprise pages and the enterprise-only section
  • A `depends_on: toolhive` constraint so SEP's PR refuses to merge until the matching toolhive version bump has landed (avoids overwriting freshly-tagged inline content)
2. New helper script: `scripts/upstream-release/sync-sep-manifests.mjs`
  • Reads `component-versions.yaml` and `enterprise-features.yaml` from the cloned SEP release
  • Updates the compatibility matrix data file (path TBD — `data/compatibility.yaml`?)
  • Materializes the features list into a structured input the skill will consume (e.g. `/tmp/sep-features.json`)
  • Optionally renders `vex.json` into the CVE transparency page
3. Enterprise-tagging convention doc

Author a doc the skill can read (e.g. `.claude/conventions/enterprise-tagging.md`) covering:

  • The exact tag/admonition syntax (`:::enterprise`? MDX component? — pick one and document it)
  • When to use inline tagging (`surface: inline-overlay`) vs. a standalone enterprise-only page (`surface: standalone`)
  • Voice/style rules for enterprise content
  • Examples of well-formed inline-tagged pages

Without this doc, the skill is guessing — this is the single biggest quality lever.

4. SEP-aware skill prompt

Either:

  • (A) Extend the existing `upstream-release-docs` skill with project-conditional branches that read `enterprise-features.yaml` and produce inline-tagged content, OR
  • (B) Add a sibling `sep-release-docs` skill that the workflow picks based on the project key

Recommend (A) since the docs-review pass is already shared and the asset-sync phase is identical — having one skill that handles both projects keeps the editorial voice consistent.

The skill needs to:

  • Map each `enterprise-features.yaml` entry to a content surface (inline edit vs. new page)
  • Reference the toolhive version pinned in `component-versions.yaml` when writing inline content (so feature docs stay version-accurate)
  • Emit `NO_CHANGES.md` when SEP ships a pure version-bump release with no narrative changes (common case — most SEP releases just re-roll the umbrella chart)
5. Reviewer-assignment tweak

The existing reviewer logic pulls contributors from the upstream release. For SEP, prefer contributors from the SEP repo + anyone tagged on `enterprise-features.yaml` entries.

Acceptance criteria

  • SEP entry in `.github/upstream-projects.yaml` with asset declarations + `depends_on` constraint
  • `sync-sep-manifests.mjs` script reading the two manifests
  • `.claude/conventions/enterprise-tagging.md` authored and linked from the skill prompt
  • Skill (or skill-pair) handles SEP releases end-to-end
  • Dry-run against a backfilled SEP release (see SEP issue) produces a sane PR
  • Reviewer assignment pulls from SEP contributors

Open questions

  • Tag/admonition syntax for inline enterprise content — does one already exist in this repo, or do we pick now?
  • Where does the compatibility matrix live and how is it currently rendered?
  • Should the SEP sync be gated behind a feature flag for the first few releases so a bad run doesn't pollute live docs?
Lenguaje dominante
TypeScript
Estrellas
4
Forks
4
Merge medio
1 d 17 min
PR fusionados (30 d)
63

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de stacklok/docs-website

Todos los issues de stacklok/docs-website

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.