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

Auto-sync docs on stacklok-enterprise-platform release

Offen
  • Stimmt etwas nicht?
#902 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
Ruhig
Tech-Stack
github-actions, javascript, typescript, yaml
Bereich
ci-cd, documentation, tooling

Rechercherichtung

Beginne mit .github/workflows/upstream-release-docs.yml, .github/upstream-projects.yaml und den vorhandenen Helfern unter scripts/upstream-release/, um den aktuellen Projektablauf zu verstehen. Untersuche anschließend die vorhandene upstream-release-docs-Skill und die Dokumentationskonventionen, bevor du die offenen Fragen klärst; abgeschlossen ist die Arbeit, wenn eine SEP-Konfiguration, eine Manifest-Synchronisierung, Richtlinien für Enterprise-Tagging, SEP-kompatibles Skill-Verhalten, eine Reviewer-Zuweisung und ein erfolgreicher nachgeholter Dry Run vorhanden sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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?
Vorherrschende Sprache
TypeScript
Sterne
4
Forks
4
Ø Merge
1 T. 1 Std.
Gemergte PRs (30 T.)
58

Entwicklungsumgebung

In Codespaces öffnen

Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.

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 stacklok/docs-website

Alle Issues in stacklok/docs-website

Ähnliche Issues

Weitere Issues zu TypeScript

Neue Issues direkt in Ihr Postfach

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