Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Auto-sync docs on stacklok-enterprise-platform release

Đang mở
  • Có gì không ổn?
#902 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tính năng
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
github-actions, javascript, typescript, yaml
Lĩnh vực
ci-cd, documentation, tooling

Hướng nghiên cứu

Bắt đầu với .github/workflows/upstream-release-docs.yml, .github/upstream-projects.yaml và các helper hiện có trong scripts/upstream-release/ để hiểu luồng hiện tại của dự án. Sau đó, xem xét skill upstream-release-docs hiện có và các quy ước về tài liệu trước khi giải quyết các câu hỏi còn bỏ ngỏ; công việc được xem là hoàn tất khi có cấu hình SEP, đồng bộ manifest, hướng dẫn gắn thẻ enterprise, hành vi của skill nhận biết SEP, phân công reviewer và một dry run backfill thành công.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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?
Ngôn ngữ chính
TypeScript
Star
4
Fork
4
Merge trung bình
1 ngày 17 phút
Pull request đã merge (30 ngày)
63

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của stacklok/docs-website

Tất cả issue của stacklok/docs-website

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.