Hacktoberfest 2026 : les issues que les mainteneurs ont marquées pour octobre, ouvertes et accessibles aux débutants. Parcourir les issues Hacktoberfest

Auto-sync docs on stacklok-enterprise-platform release

Ouverte
  • Quelque chose ne va pas ?
#902 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
35/100
Type d'issue
Fonctionnalité
Clarté
Plutôt claire
Activité
Calme
Stack technique
github-actions, javascript, typescript, yaml
Domaine
ci-cd, documentation, tooling

Piste de recherche

Commencez par .github/workflows/upstream-release-docs.yml, .github/upstream-projects.yaml et les helpers existants sous scripts/upstream-release/ afin de comprendre le flux actuel du projet. Examinez ensuite la skill upstream-release-docs existante et les conventions de documentation avant de résoudre les questions ouvertes ; le travail est terminé lorsqu’une configuration SEP, une synchronisation du manifeste, des consignes de marquage enterprise, un comportement de la skill compatible avec SEP, l’attribution d’un reviewer et un dry run de rattrapage réussi sont en place.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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?
Langage dominant
TypeScript
Étoiles
4
Forks
4
Merge moyen
1 j 1 h
PR mergées (30 j)
60

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de stacklok/docs-website

Toutes les issues de stacklok/docs-website

Issues similaires

Plus d'issues TypeScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.