You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/09/24 13:41:46 UTC
(skywalking-website) branch master updated: Serve Latest from the project, and build 0.5.0 documentation from docs/v0.5.0 (#938)
This is an automated email from the ASF dual-hosted git repository.
wu-sheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/skywalking-website.git
The following commit(s) were added to refs/heads/master by this push:
new 3391ad5eb670 Serve Latest from the project, and build 0.5.0 documentation from docs/v0.5.0 (#938)
3391ad5eb670 is described below
commit 3391ad5eb67025d9f1a580bf3e476f8a6a42fa2b
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Thu Sep 24 21:41:41 2026 +0800
Serve Latest from the project, and build 0.5.0 documentation from docs/v0.5.0 (#938)
* Build the AI Sessionizer 0.5.0 documentation from docs/v0.5.0
The numbered and the Latest documentation of 0.5.0 now build from the
head of docs/v0.5.0 in apache/skywalking-ai-sessionizer, as 0.4.0's build
from docs/v0.4.0. It is the v0.5.0 tag with documentation fixes only: the
parts of #38 there that apply to 0.5.0, and what a set source_root means
for claude-code-local.
* Serve Latest from the project, on the latest release's own pin
A release carried latestLink and latestCommitId, so the Latest tree was
configured once per release and its pin was a second copy of the release
pin. They could drift, and in skywalking-go they had: Latest served
41a66149 while v0.7.0 served the tag.
The project now says where its two generated trees live:
docs:
link: /docs/skywalking-go/next/readme/
latest: /docs/skywalking-go/latest/readme/
Latest renders the commitId of the release marked latest, so a release
carries one pin and the two cannot disagree. The project-level next block
is gone; its keys moved to docs. skywalking-go v0.7.0 now pins 41a66149,
the documentation commit its Latest tree already served, so the numbered
tree gains the same fixes and no page changes.
The validator rejects the retired keys by name, and requires a commitId
on the latest release when the project serves Latest.
---
CLAUDE.md | 35 +++---
README.md | 30 +++---
data/get-started.yml | 7 +-
data/projects.yml | 162 +++++++++++-----------------
layouts/get-started/baseof.html | 4 +-
layouts/partials/project-catalog-data.html | 14 +--
layouts/partials/project-doc-versions.html | 23 ++--
layouts/shortcodes/home-agent-workflow.html | 2 +-
scripts/project-config.js | 32 +++---
scripts/project-config.test.js | 35 +++---
10 files changed, 160 insertions(+), 184 deletions(-)
diff --git a/CLAUDE.md b/CLAUDE.md
index d6a9a4aa9927..b74411401c50 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -29,7 +29,7 @@ description: "Release Apache SkyWalking <Component Name> <VERSION>."
`data/projects.yml` owns the catalog, project metadata, documentation versions,
downloads, and container images. Its structure is `catalogs[]` → `projects[]` →
-`next.docs` / `releases[]` / `dockerImages[]`. Catalogs have `id`, `name`, `description`, and optional
+`docs` / `releases[]` / `dockerImages[]`. Catalogs have `id`, `name`, `description`, and optional
`note`; project `featured` and `menu` metadata control cards and shortcuts, with
shortcut groups in the top-level `menu` list. Keep repository identities and
existing `downloadAliases` stable.
@@ -40,7 +40,7 @@ repositories and remain available independently of the selected release.
`data/get-started.yml` owns both Showcase and platform installation, separate
from `data/projects.yml`. Its `showcase` block contains Showcase metadata,
-`next.docs`, and `quickstart`; its `skywalking` block contains installation commands.
+`docs`, and `quickstart`; its `skywalking` block contains installation commands.
See the complete YAML example in README.md. Run `node scripts/project-config.js`
for local configuration validation without fetching repositories or artifacts.
@@ -92,27 +92,30 @@ Use `Mon. DDth, YYYY` with ordinal suffixes: 1st, 2nd, 3rd, all others th (e.g.
## Documentation in data/projects.yml
-- `next.docs` defines development documentation through `link`, optional explicit
- `commitId`, and optional display `label`.
+- The project's `docs` block defines the two generated trees: `link` is the
+ development documentation (Next), and `latest` is where the Latest tree is
+ served. Optional `commitId` pins Next explicitly, and optional `label`
+ customizes its displayed name.
- A release's `docs.link` and `docs.commitId` define its numbered documentation;
optional `docs.label` customizes its displayed name.
-- On the release marked `latest: true`, `docs.latestLink` generates the Latest
- entry and requires an explicit `docs.latestCommitId`. Do not add separate
- `Next` or `Latest` releases.
+- Latest renders the `commitId` of the release marked `latest: true`. A release
+ carries one pin, and there is no separate Latest pin to keep in step. Do not
+ add separate `Next` or `Latest` releases. `latestLink` and `latestCommitId` on
+ a release are retired, and the validator rejects them.
- Hugo-hosted documentation needs project `repoUrl` and paths of the form
`/docs/<repo-slug>/<version>/readme/`. External documentation can use HTTP(S)
- links in either `next.docs` or release `docs`.
+ links in the project `docs` or a release's `docs`.
-**Explicit documentation commit pins are authoritative.** `docs.commitId` and
-`docs.latestCommitId` can intentionally differ from each other and from the
-release tag. Preserve them exactly; never infer, replace, or synchronize them
-from tag commits. Set new pins only from explicitly supplied documentation
-revisions, and leave existing pins unchanged during unrelated release updates.
+**Explicit documentation commit pins are authoritative.** `docs.commitId` can
+intentionally differ from the release tag, as when a documentation branch carries
+fixes made after the tag. Preserve pins exactly; never infer or replace them from
+tag commits. Set new pins only from explicitly supplied documentation revisions,
+and leave existing pins unchanged during unrelated release updates.
`layouts/partials/seo/doc-canonical-map.html` compares the generated entries'
-commit IDs. A numbered tree canonicalizes to Latest only when their explicit
-pins match. Different pins remain self-canonical; do not alter pins to force a
-canonical relationship.
+commit IDs, so the numbered tree of the latest release canonicalizes to Latest,
+which renders the same commit. Older versions never match and stay
+self-canonical.
## SEO metadata
diff --git a/README.md b/README.md
index d71ca598186f..6a4e34fdaefb 100755
--- a/README.md
+++ b/README.md
@@ -31,8 +31,9 @@ featured cards and menu shortcuts; the top-level `menu` list configures shortcut
groups. Project shortcuts open the matching catalog card, where visitors can
choose documentation or downloads.
-Development documentation belongs in `next.docs`. Released versions belong in
-`releases`, with exactly one `latest: true` when the list is nonempty. Projects
+Development documentation belongs in the project's `docs.link`, and `docs.latest`
+is where the Latest tree is served. Released versions belong in `releases`, with
+exactly one `latest: true` when the list is nonempty. Projects
without releases can use `releases: []`. For example:
```yaml
@@ -46,17 +47,15 @@ catalogs:
user: apache
repoUrl: https://github.com/apache/skywalking.git
description: SkyWalking primary repository and docs.
- next:
- docs:
- link: /docs/main/next/readme/
+ docs:
+ link: /docs/main/next/readme/
+ latest: /docs/main/latest/readme/
releases:
- version: v11.0.0
latest: true
docs:
link: /docs/main/v11.0.0/readme/
commitId: 6f1fd78e872f1d380a14f271c26e8d68eb2430fc
- latestLink: /docs/main/latest/readme/
- latestCommitId: 6f1fd78e872f1d380a14f271c26e8d68eb2430fc
downloads:
- name: Source archive
type: source
@@ -69,12 +68,13 @@ catalogs:
menu: []
```
-`docs.link` and `docs.commitId` define the numbered documentation. The latest
-release's `docs.latestLink` generates the Latest documentation choice and requires
-its own explicit `docs.latestCommitId`. **These two commit pins are authoritative
-and may intentionally differ from each other and from the release tag. Preserve
-them exactly; never infer or replace them from tags.** Optional `docs.label`
-customizes the displayed version name, including for `next.docs`.
+A release's `docs.link` and `docs.commitId` define its numbered documentation.
+The project's `docs.latest` generates the Latest choice, which renders the
+`commitId` of the release marked `latest: true`, so a release carries one pin and
+Latest can never drift from it. **Commit pins are authoritative and may differ
+from the release tag. Preserve them exactly; never infer or replace them from
+tags.** Optional `docs.label` customizes the displayed version name, including
+for the project's development documentation.
Each release can have documentation, downloads, or both. Each download has `name`,
`type` (`source` or `binary`), and `link`; provide `asc` and `sha512` together when
@@ -100,7 +100,7 @@ matches automatically, and keeps the selected project's category expanded.
The separate `/get-started/` page contains Showcase and installation quickstarts.
Both come from `data/get-started.yml`, separate from the project catalog. Its
-`showcase` block contains Showcase's identity, `next.docs`, and `quickstart`
+`showcase` block contains Showcase's identity, `docs`, and `quickstart`
commands; its `skywalking` block contains platform installation commands.
`showcase.diagram` defines the interactive application and observability graphs,
@@ -112,7 +112,7 @@ the music application; BanyanDB stores SkyWalking telemetry. Show ecosystem
integrations separately from native agents: the Showcase collectors export
OTLP metrics, while its Kubernetes mesh scenario supplies ALS access logs and
Zipkin traces. Broader receiver capabilities belong in the component details.
-The documentation link comes from `showcase.next.docs.link`.
+The documentation link comes from `showcase.docs.link`.
#### Search and AI answers
diff --git a/data/get-started.yml b/data/get-started.yml
index 5e495d037329..ec7f4e70c6d4 100644
--- a/data/get-started.yml
+++ b/data/get-started.yml
@@ -7,10 +7,9 @@ showcase:
user: apache
repo: skywalking-showcase
repoUrl: https://github.com/apache/skywalking-showcase.git
- next:
- docs:
- link: /docs/skywalking-showcase/next/readme/
- label: showcase for v10
+ docs:
+ link: /docs/skywalking-showcase/next/readme/
+ label: showcase for v10
quickstart:
title: Run the Showcase
blurb: A demo music application pre-wired with distributed tracing, metrics, logs and profiling — see SkyWalking end-to-end before installing anything.
diff --git a/data/projects.yml b/data/projects.yml
index 4f696392bdaf..22f892ce32b1 100644
--- a/data/projects.yml
+++ b/data/projects.yml
@@ -1,7 +1,8 @@
# Unified project catalog. Each released version owns its documentation and downloads.
-# Keep exactly one latest release per project; next contains development documentation.
+# Keep exactly one latest release per project; project docs.link is the development documentation.
# Documentation commit IDs are intentional: preserve them and never infer them from release tags.
-# latestCommitId pins the Latest documentation independently of the numbered release's commitId.
+# Project docs.latest is where the Latest tree is served; it always renders the commitId of the
+# release marked latest, so a release carries one pin and the two can never drift apart.
# Project dockerImages entries are Docker Hub repository links, not version-pinned image tags.
catalogs:
- id: SkyWalkingServers
@@ -27,9 +28,9 @@ catalogs:
column: 0
order: 0
description: Core observability server
- next:
- docs:
- link: /docs/main/next/readme/
+ docs:
+ link: /docs/main/next/readme/
+ latest: /docs/main/latest/readme/
dockerImages:
- name: SkyWalking OAP Server
icon: O
@@ -46,8 +47,6 @@ catalogs:
docs:
link: /docs/main/v11.0.0/readme/
commitId: 6f1fd78e872f1d380a14f271c26e8d68eb2430fc
- latestLink: /docs/main/latest/readme/
- latestCommitId: 6f1fd78e872f1d380a14f271c26e8d68eb2430fc
downloads:
- name: Source archive
type: source
@@ -172,9 +171,9 @@ catalogs:
repoUrl: https://github.com/apache/skywalking-graalvm-distro.git
icon: skywalking
description: A re-distribution of the Apache SkyWalking OAP server based on GraalVM native image. This is experimental.
- next:
- docs:
- link: /docs/skywalking-graalvm-distro/next/readme/
+ docs:
+ link: /docs/skywalking-graalvm-distro/next/readme/
+ latest: /docs/skywalking-graalvm-distro/latest/readme/
dockerImages:
- name: SkyWalking OAP GraalVM Distro
icon: O
@@ -188,8 +187,6 @@ catalogs:
link: /docs/skywalking-graalvm-distro/v0.4.0/readme/
commitId: 1e5dfedd0dfa434c4c339d9d1d1a7f8097d5df97
label: 0.4.0 (SkyWalking 11.0.0)
- latestLink: /docs/skywalking-graalvm-distro/latest/readme/
- latestCommitId: 1e5dfedd0dfa434c4c339d9d1d1a7f8097d5df97
downloads:
- name: Source archive
type: source
@@ -260,9 +257,9 @@ catalogs:
column: 0
order: 2
description: Next-generation UI
- next:
- docs:
- link: /docs/skywalking-horizon-ui/next/readme/
+ docs:
+ link: /docs/skywalking-horizon-ui/next/readme/
+ latest: /docs/skywalking-horizon-ui/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/horizon-ui/
releases:
@@ -271,8 +268,6 @@ catalogs:
docs:
link: /docs/skywalking-horizon-ui/v1.0.0/readme/
commitId: 19ca126d9bd931b51af86e31086bf615dad3decd
- latestLink: /docs/skywalking-horizon-ui/latest/readme/
- latestCommitId: 19ca126d9bd931b51af86e31086bf615dad3decd
downloads:
- name: Source archive
type: source
@@ -292,9 +287,8 @@ catalogs:
user: apache
icon: skywalking
description: SkyWalking Grafana Plugins provide extensions to visualize topology on Grafana. Metrics visualization is supported through PromQL.
- next:
- docs:
- link: https://github.com/apache/skywalking-grafana-plugins
+ docs:
+ link: https://github.com/apache/skywalking-grafana-plugins
dockerImages: []
releases:
- version: v0.1.0
@@ -328,9 +322,9 @@ catalogs:
column: 0
order: 3
description: AI agent observability
- next:
- docs:
- link: /docs/skywalking-ai-sessionizer/next/readme/
+ docs:
+ link: /docs/skywalking-ai-sessionizer/next/readme/
+ latest: /docs/skywalking-ai-sessionizer/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/ai-sessionizer/
releases:
@@ -338,9 +332,7 @@ catalogs:
latest: true
docs:
link: /docs/skywalking-ai-sessionizer/v0.5.0/readme/
- commitId: 8743b2cb427d87704a338cfc21c22c015bdde0b6
- latestLink: /docs/skywalking-ai-sessionizer/latest/readme/
- latestCommitId: 8743b2cb427d87704a338cfc21c22c015bdde0b6
+ commitId: 532cc2de7c0443290817ab5fa211ffdcac151a14
downloads:
- name: Source archive
type: source
@@ -439,9 +431,9 @@ catalogs:
column: 0
order: 1
description: Observability database
- next:
- docs:
- link: /docs/skywalking-banyandb/next/readme/
+ docs:
+ link: /docs/skywalking-banyandb/next/readme/
+ latest: /docs/skywalking-banyandb/latest/readme/
dockerImages:
- name: SkyWalking BanyanDB
icon: R
@@ -462,8 +454,6 @@ catalogs:
docs:
link: /docs/skywalking-banyandb/v0.11.1/readme/
commitId: 3f4534fafdf9255c21f3b5a2a8ec733a49f2f1a0
- latestLink: /docs/skywalking-banyandb/latest/readme/
- latestCommitId: 3f4534fafdf9255c21f3b5a2a8ec733a49f2f1a0
downloads:
- name: Source archive
type: source
@@ -529,9 +519,8 @@ catalogs:
user: apache
icon: banyan-db
description: Protocol definitions in Protobuf/gRPC for BanyanDB clients
- next:
- docs:
- link: https://github.com/apache/skywalking-banyandb-client-proto/blob/main/README.md
+ docs:
+ link: https://github.com/apache/skywalking-banyandb-client-proto/blob/main/README.md
dockerImages: []
releases: []
- name: BanyanDB Helm
@@ -539,9 +528,8 @@ catalogs:
user: apache
icon: banyan-db
description: BanyanDB Helm Chart repository provides ways to install and configure BanyanDB in a Kubernetes cluster.
- next:
- docs:
- link: https://github.com/apache/skywalking-banyandb-helm/blob/master/README.md
+ docs:
+ link: https://github.com/apache/skywalking-banyandb-helm/blob/master/README.md
dockerImages:
- name: SkyWalking BanyanDB Helm
icon: R
@@ -578,9 +566,9 @@ catalogs:
column: 0
order: 0
description: Java tracing and profiling
- next:
- docs:
- link: /docs/skywalking-java/next/readme/
+ docs:
+ link: /docs/skywalking-java/next/readme/
+ latest: /docs/skywalking-java/latest/readme/
dockerImages:
- name: SkyWalking Java Agent
icon: J
@@ -593,8 +581,6 @@ catalogs:
docs:
link: /docs/skywalking-java/v9.7.0/readme/
commitId: 7a6c1e46c9c8ee7f26988caf57c5023c1ff4fb42
- latestLink: /docs/skywalking-java/latest/readme/
- latestCommitId: 7a6c1e46c9c8ee7f26988caf57c5023c1ff4fb42
downloads:
- name: Source archive
type: source
@@ -740,9 +726,9 @@ catalogs:
column: 0
order: 2
description: Python tracing and profiling
- next:
- docs:
- link: /docs/skywalking-python/next/readme/
+ docs:
+ link: /docs/skywalking-python/next/readme/
+ latest: /docs/skywalking-python/latest/readme/
dockerImages:
- name: SkyWalking Python Agent
icon: P
@@ -755,8 +741,6 @@ catalogs:
docs:
link: /docs/skywalking-python/v1.3.0/readme/
commitId: 1bd4692f927a4c6156bc25d18d36d9cba76405df
- latestLink: /docs/skywalking-python/latest/readme/
- latestCommitId: 1bd4692f927a4c6156bc25d18d36d9cba76405df
downloads:
- name: Source archive
type: source
@@ -796,9 +780,9 @@ catalogs:
column: 0
order: 3
description: Node.js distributed tracing
- next:
- docs:
- link: /docs/skywalking-nodejs/next/readme/
+ docs:
+ link: /docs/skywalking-nodejs/next/readme/
+ latest: /docs/skywalking-nodejs/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/node-js/
releases:
@@ -807,8 +791,6 @@ catalogs:
docs:
link: /docs/skywalking-nodejs/v0.9.0/readme/
commitId: bf5dc68ed6e36254aed2aa55abe5f72ba12bddc3
- latestLink: /docs/skywalking-nodejs/latest/readme/
- latestCommitId: bf5dc68ed6e36254aed2aa55abe5f72ba12bddc3
downloads:
- name: Source archive
type: source
@@ -832,9 +814,9 @@ catalogs:
column: 0
order: 1
description: Go tracing and metrics
- next:
- docs:
- link: /docs/skywalking-go/next/readme/
+ docs:
+ link: /docs/skywalking-go/next/readme/
+ latest: /docs/skywalking-go/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/go/
releases:
@@ -842,9 +824,7 @@ catalogs:
latest: true
docs:
link: /docs/skywalking-go/v0.7.0/readme/
- commitId: b52ef5762fab16d85704a7d35b8968165d351b85
- latestLink: /docs/skywalking-go/latest/readme/
- latestCommitId: 41a661492feea65015e8300205c139dcf06e99c6
+ commitId: 41a661492feea65015e8300205c139dcf06e99c6
downloads:
- name: Source archive
type: source
@@ -864,9 +844,8 @@ catalogs:
user: apache
icon: sw-rust
description: The Rust Agent for Apache SkyWalking, which provides the native tracing/metrics/logging abilities for Rust projects.
- next:
- docs:
- link: https://github.com/apache/skywalking-rust
+ docs:
+ link: https://github.com/apache/skywalking-rust
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/rust/
releases:
@@ -897,9 +876,9 @@ catalogs:
column: 0
order: 4
description: PHP distributed tracing
- next:
- docs:
- link: /docs/skywalking-php/next/readme/
+ docs:
+ link: /docs/skywalking-php/next/readme/
+ latest: /docs/skywalking-php/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/php/
releases:
@@ -908,8 +887,6 @@ catalogs:
docs:
link: /docs/skywalking-php/v1.1.0/readme/
commitId: 5a09c4b68868b88b545de4ef3cc8a51dff5bf383
- latestLink: /docs/skywalking-php/latest/readme/
- latestCommitId: 5a09c4b68868b88b545de4ef3cc8a51dff5bf383
downloads:
- name: Source archive
type: source
@@ -952,9 +929,9 @@ catalogs:
repoUrl: https://github.com/apache/skywalking-ruby.git
icon: ruby-agent
description: The Ruby Agent for Apache SkyWalking, which provides the native tracing abilities for Ruby projects.
- next:
- docs:
- link: /docs/skywalking-ruby/next/readme/
+ docs:
+ link: /docs/skywalking-ruby/next/readme/
+ latest: /docs/skywalking-ruby/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/ruby/
releases:
@@ -963,8 +940,6 @@ catalogs:
docs:
link: /docs/skywalking-ruby/v0.1.0/readme/
commitId: a3fc0c7b59c2071edea999833b71daccac62ce2f
- latestLink: /docs/skywalking-ruby/latest/readme/
- latestCommitId: a3fc0c7b59c2071edea999833b71daccac62ce2f
downloads:
- name: Source archive
type: source
@@ -1036,9 +1011,9 @@ catalogs:
column: 1
order: 1
description: Lightweight telemetry collector
- next:
- docs:
- link: /docs/skywalking-satellite/next/readme/
+ docs:
+ link: /docs/skywalking-satellite/next/readme/
+ latest: /docs/skywalking-satellite/latest/readme/
dockerImages:
- name: SkyWalking Satellite
icon: S
@@ -1051,8 +1026,6 @@ catalogs:
docs:
link: /docs/skywalking-satellite/v1.3.0/readme/
commitId: 79f861e6bc08bf872413c93f34f4cfe2ee719514
- latestLink: /docs/skywalking-satellite/latest/readme/
- latestCommitId: 79f861e6bc08bf872413c93f34f4cfe2ee719514
downloads:
- name: Source archive
type: source
@@ -1078,9 +1051,8 @@ catalogs:
column: 1
order: 2
description: Kubernetes event collection
- next:
- docs:
- link: https://github.com/apache/skywalking-kubernetes-event-exporter/tree/main#configurations
+ docs:
+ link: https://github.com/apache/skywalking-kubernetes-event-exporter/tree/main#configurations
dockerImages:
- name: SkyWalking Kubernetes Event Exporter
icon: E
@@ -1118,9 +1090,9 @@ catalogs:
column: 1
order: 0
description: eBPF metrics and profiling
- next:
- docs:
- link: /docs/skywalking-rover/next/readme/
+ docs:
+ link: /docs/skywalking-rover/next/readme/
+ latest: /docs/skywalking-rover/latest/readme/
dockerImages:
- name: SkyWalking Rover
icon: R
@@ -1133,8 +1105,6 @@ catalogs:
docs:
link: /docs/skywalking-rover/v0.7.0/readme/
commitId: e0fc8f7c72a8b57dab6ea9552d7be2b40b134fe8
- latestLink: /docs/skywalking-rover/latest/readme/
- latestCommitId: e0fc8f7c72a8b57dab6ea9552d7be2b40b134fe8
downloads:
- name: Source archive
type: source
@@ -1237,9 +1207,9 @@ catalogs:
column: 0
order: 2
description: Deploy SkyWalking with Helm
- next:
- docs:
- link: /docs/skywalking-helm/next/readme/
+ docs:
+ link: /docs/skywalking-helm/next/readme/
+ latest: /docs/skywalking-helm/latest/readme/
dockerImages:
- name: SkyWalking Kubernetes Helm
icon: H
@@ -1252,8 +1222,6 @@ catalogs:
docs:
link: /docs/skywalking-helm/v5.0.0/readme/
commitId: 6fe2c783ba2639b0d9ae62edde25fb4d60f3b5e6
- latestLink: /docs/skywalking-helm/latest/readme/
- latestCommitId: 6fe2c783ba2639b0d9ae62edde25fb4d60f3b5e6
downloads:
- name: Source archive
type: source
@@ -1294,9 +1262,9 @@ catalogs:
column: 0
order: 3
description: Kubernetes operator
- next:
- docs:
- link: /docs/skywalking-swck/next/readme/
+ docs:
+ link: /docs/skywalking-swck/next/readme/
+ latest: /docs/skywalking-swck/latest/readme/
dockerImages:
- name: SkyWalking Cloud on Kubernetes
icon: K
@@ -1309,8 +1277,6 @@ catalogs:
docs:
link: /docs/skywalking-swck/v0.11.0/readme/
commitId: 29a5ea771330f8b205a9e3a9a876928a1d8914e5
- latestLink: /docs/skywalking-swck/latest/readme/
- latestCommitId: 29a5ea771330f8b205a9e3a9a876928a1d8914e5
downloads:
- name: Source archive
type: source
@@ -1423,9 +1389,9 @@ catalogs:
repoUrl: https://github.com/apache/skywalking-infra-e2e.git
icon: skywalking-agent-test-tool
description: An End-to-End Testing framework that aims to help developers to set up, debug, and verify E2E tests with ease.
- next:
- docs:
- link: /docs/skywalking-infra-e2e/next/readme/
+ docs:
+ link: /docs/skywalking-infra-e2e/next/readme/
+ latest: /docs/skywalking-infra-e2e/latest/readme/
dockerImages: []
archive: https://archive.apache.org/dist/skywalking/infra-e2e/
releases:
@@ -1434,8 +1400,6 @@ catalogs:
docs:
link: /docs/skywalking-infra-e2e/v1.3.0/readme/
commitId: 1485ae03f0ad90496ad7626a5ae4a6a73a1f6296
- latestLink: /docs/skywalking-infra-e2e/latest/readme/
- latestCommitId: 1485ae03f0ad90496ad7626a5ae4a6a73a1f6296
downloads:
- name: Source archive
type: source
diff --git a/layouts/get-started/baseof.html b/layouts/get-started/baseof.html
index aae7c2d7bf37..d3d568011b16 100644
--- a/layouts/get-started/baseof.html
+++ b/layouts/get-started/baseof.html
@@ -19,7 +19,7 @@
{{ with (index .Site.Data "get-started").showcase }}
<div class="qs-shell qs-diagram-section">
- {{ partial "showcase-diagram.html" (merge .diagram (dict "docsLink" .next.docs.link)) }}
+ {{ partial "showcase-diagram.html" (merge .diagram (dict "docsLink" .docs.link)) }}
</div>
{{ end }}
@@ -29,7 +29,7 @@
{{ $gettingStarted := index .Site.Data "get-started" }}
{{ range $key := slice "showcase" "skywalking" }}
{{ $q := index $gettingStarted $key }}
- {{ if eq $key "showcase" }}{{ $q = merge $q.quickstart (dict "docsLink" $q.next.docs.link) }}{{ end }}
+ {{ if eq $key "showcase" }}{{ $q = merge $q.quickstart (dict "docsLink" $q.docs.link) }}{{ end }}
<article class="qs-card" id="qs-{{ $key }}" aria-labelledby="qs-title-{{ $key }}">
<div class="qs-card-top">
<span class="qs-badge{{ if eq $key "showcase" }} is-rec{{ end }}">{{ $q.badge }}</span>
diff --git a/layouts/partials/project-catalog-data.html b/layouts/partials/project-catalog-data.html
index 9b0b7a8f03bf..7e852fe1e509 100644
--- a/layouts/partials/project-catalog-data.html
+++ b/layouts/partials/project-catalog-data.html
@@ -7,19 +7,21 @@
{{- $versions := slice -}}
{{- $downloads := slice -}}
{{- $images := .dockerImages | default slice -}}
+ {{- $latestLink := "" -}}
+ {{- with .docs }}{{ $latestLink = default "" .latest }}{{ end -}}
{{- range .releases -}}
{{- if .downloads }}{{ $downloads = $downloads | append . }}{{ end -}}
{{- if and .latest .docs -}}
- {{- $primary = dict "link" (default .docs.link .docs.latestLink) "version" .version -}}
+ {{- $primary = dict "link" (default .docs.link $latestLink) "version" .version -}}
{{- end -}}
{{- end -}}
{{- if not $primary -}}
- {{- with .next.docs }}{{ $primary = dict "link" .link "version" "Next" }}{{ end -}}
+ {{- with .docs }}{{ $primary = dict "link" .link "version" "Next" }}{{ end -}}
{{- end -}}
{{- if not $primary -}}
{{- range .releases }}{{ if .docs }}{{ $primary = dict "link" .docs.link "version" .version }}{{ break }}{{ end }}{{ end -}}
{{- end -}}
- {{- with .next.docs -}}
+ {{- with .docs -}}
{{- $versions = $versions | append (dict "label" (default "Next (development)" .label) "link" .link "selected" (eq $primary.version "Next") "downloadLink" "") -}}
{{- end -}}
{{- $primaryDownload := printf "/downloads/#%s" .repo -}}
@@ -30,7 +32,7 @@
{{- $link := .link -}}
{{- if $release.latest -}}
{{- $label = printf "Latest release (%s)" $label -}}
- {{- $link = default .link .latestLink -}}
+ {{- $link = default .link $latestLink -}}
{{- end -}}
{{- $downloadLink := "" -}}
{{- if $release.downloads }}{{ $downloadLink = printf "/downloads/?version=%s#%s" ($release.version | urlquery) $project.repo }}{{ end -}}
@@ -42,8 +44,8 @@
{{- else -}}
{{- $versions = $versions | append $version -}}
{{- end -}}
- {{- if and $release.latest .latestLink -}}
- {{- /* Latest and numbered docs may intentionally use different commits. */ -}}
+ {{- if and $release.latest (ne $latestLink "") -}}
+ {{- /* The entry above points at Latest, so the numbered URL is listed too. */ -}}
{{- $versions = $versions | append (dict "label" (default $release.version .label) "link" .link "selected" false "downloadLink" $downloadLink) -}}
{{- end -}}
{{- end -}}
diff --git a/layouts/partials/project-doc-versions.html b/layouts/partials/project-doc-versions.html
index c2a7260f5866..a463c120763a 100644
--- a/layouts/partials/project-doc-versions.html
+++ b/layouts/partials/project-doc-versions.html
@@ -1,20 +1,21 @@
{{- /* Adapt a project's development docs and releases to the flat docs list.
- Latest and numbered documentation can intentionally pin different commits. */ -}}
+ Latest is the release marked latest, served at its own URL from the same
+ commit, so the two never drift apart. */ -}}
{{- $versions := slice -}}
-{{- with .next -}}
- {{- with .docs -}}
- {{- $version := dict "version" "Next" "link" .link -}}
- {{- with .commitId }}{{ $version = merge $version (dict "commitId" .) }}{{ end -}}
- {{- with .label }}{{ $version = merge $version (dict "versionName" .) }}{{ end -}}
- {{- $versions = $versions | append $version -}}
- {{- end -}}
+{{- $latestLink := "" -}}
+{{- with .docs -}}
+ {{- $latestLink = default "" .latest -}}
+ {{- $version := dict "version" "Next" "link" .link -}}
+ {{- with .commitId }}{{ $version = merge $version (dict "commitId" .) }}{{ end -}}
+ {{- with .label }}{{ $version = merge $version (dict "versionName" .) }}{{ end -}}
+ {{- $versions = $versions | append $version -}}
{{- end -}}
{{- range .releases -}}
{{- $release := . -}}
{{- with .docs -}}
- {{- if and $release.latest .latestLink -}}
- {{- $latest := dict "version" "Latest" "link" .latestLink -}}
- {{- with .latestCommitId }}{{ $latest = merge $latest (dict "commitId" .) }}{{ end -}}
+ {{- if and $release.latest (ne $latestLink "") -}}
+ {{- $latest := dict "version" "Latest" "link" $latestLink -}}
+ {{- with .commitId }}{{ $latest = merge $latest (dict "commitId" .) }}{{ end -}}
{{- $versions = $versions | append $latest -}}
{{- end -}}
{{- $version := dict "version" $release.version "link" .link -}}
diff --git a/layouts/shortcodes/home-agent-workflow.html b/layouts/shortcodes/home-agent-workflow.html
index 9675c7579ae2..b802801efaf6 100644
--- a/layouts/shortcodes/home-agent-workflow.html
+++ b/layouts/shortcodes/home-agent-workflow.html
@@ -1,6 +1,6 @@
{{- $catalog := partialCached "project-catalog-data.html" .Page.Site -}}
{{- $sessionizer := (index $catalog "skywalking-ai-sessionizer").project -}}
-{{- $sessionizerLink := $sessionizer.next.docs.link -}}
+{{- $sessionizerLink := $sessionizer.docs.link -}}
{{- $previews := slice
(dict "id" "usage" "title" "Usage"
"summary" "See token patterns across agents, sessions, and machines."
diff --git a/scripts/project-config.js b/scripts/project-config.js
index 1011eb6bc74e..19ad133f442e 100644
--- a/scripts/project-config.js
+++ b/scripts/project-config.js
@@ -62,9 +62,16 @@ function validateProjectConfig(config) {
check(Array.isArray(project.extraContributors), `${where}.extraContributors must be an array`);
project.extraContributors.forEach((person, index) => check(isObject(person) && isText(person.login), `${where}.extraContributors[${index}] requires login`));
}
- if (project.next !== undefined) {
- check(isObject(project.next), `${where}.next must be an object`);
- validateDocs(project.next.docs, project, 'Next', `${where}.next.docs`);
+ if (project.docs !== undefined) {
+ validateDocs(project.docs, project, 'Next', `${where}.docs`);
+ if (project.docs.latest !== undefined) {
+ check(/^\/docs\/[^/?#\s]+\/latest\/readme\/$/.test(project.docs.latest), `${where}.docs.latest must be a /docs/.../latest/readme/ path`);
+ // Latest serves the same documentation tree as the other versions of
+ // this project, so it sits under the same slug.
+ check(project.docs.latest.split('/')[2] === project.docs.link.split('/')[2], `${where}.docs.latest must serve the same documentation as ${where}.docs.link`);
+ check(!localDocs.has(project.docs.latest.toLowerCase()), `duplicate docs link ${project.docs.latest}`);
+ localDocs.add(project.docs.latest.toLowerCase());
+ }
}
const releases = project.releases === undefined ? [] : project.releases;
check(Array.isArray(releases), `${where}.releases must be an array`);
@@ -82,12 +89,10 @@ function validateProjectConfig(config) {
if (release.latest) latestCount++;
if (release.docs !== undefined) {
validateDocs(release.docs, project, release.version, `${releasePath}.docs`);
- if (release.docs.latestLink !== undefined) {
- check(/^\/docs\/[^/?#\s]+\/latest\/readme\/$/.test(release.docs.latestLink), `${releasePath}.docs.latestLink must be a /docs/.../latest/readme/ path`);
- check(isText(release.docs.latestCommitId), `${releasePath}.docs.latestLink requires an explicit latestCommitId`);
- if (release.latest) validateDocs({...release.docs, link: release.docs.latestLink, commitId: release.docs.latestCommitId}, project, 'Latest', `${releasePath}.docs latest alias`);
- } else if (release.docs.latestCommitId !== undefined) {
- check(false, `${releasePath}.docs.latestCommitId requires latestLink`);
+ ['latestLink', 'latestCommitId'].forEach(field => check(release.docs[field] === undefined, `${releasePath}.docs.${field} is gone: the Latest tree is served at ${where}.docs.latest and renders the commitId of the release marked latest`));
+ // The Latest tree renders this pin, so it must be there to render.
+ if (release.latest && project.docs !== undefined && project.docs.latest !== undefined) {
+ check(isText(release.docs.commitId), `${releasePath}.docs requires a commitId: ${where}.docs.latest renders it`);
}
}
const downloads = release.downloads === undefined ? [] : release.downloads;
@@ -153,12 +158,13 @@ function docsForProject(project) {
if (entry.commitId) doc.commitId = entry.commitId;
docs.push(doc);
}
- if (project.next && project.next.docs) add('Next', project.next.docs);
+ if (project.docs) add('Next', project.docs);
const releases = project.releases || [];
const latest = releases.find(release => release.latest);
- if (latest && latest.docs && latest.docs.latestLink) {
- // Latest can intentionally use a documentation fix newer than the release pin.
- add('Latest', {link: latest.docs.latestLink, commitId: latest.docs.latestCommitId});
+ if (project.docs && project.docs.latest && latest && latest.docs) {
+ // Latest is the release marked latest, served at its own URL, from the
+ // same commit. The two can never drift apart.
+ add('Latest', {link: project.docs.latest, commitId: latest.docs.commitId});
}
releases.forEach(release => { if (release.docs) add(release.version, release.docs); });
return docs;
diff --git a/scripts/project-config.test.js b/scripts/project-config.test.js
index 8a2e1752d1cf..8e3623428edc 100644
--- a/scripts/project-config.test.js
+++ b/scripts/project-config.test.js
@@ -9,13 +9,10 @@ function fixture() {
name: 'Example', user: 'apache', repo: 'example', repoUrl: 'https://github.com/apache/example.git',
icon: 'example', description: 'Example project.', extraContributors: [{login: 'extra-person'}],
dockerImages: [{name: 'Server', link: 'https://hub.docker.com/r/apache/example'}],
- next: {docs: {link: '/docs/example/next/readme/', commitId: 'main', label: 'Development'}},
+ docs: {link: '/docs/example/next/readme/', latest: '/docs/example/latest/readme/', commitId: 'main', label: 'Development'},
releases: [{
version: 'v2.0.0', latest: true,
- docs: {
- link: '/docs/example/v2.0.0/readme/', commitId: 'release-pin', label: '2.0.0 (Platform 11)',
- latestLink: '/docs/example/latest/readme/', latestCommitId: 'latest-docs-fix-pin',
- },
+ docs: {link: '/docs/example/v2.0.0/readme/', commitId: 'release-pin', label: '2.0.0 (Platform 11)'},
downloads: [{name: 'Source archive', type: 'source', link: 'https://downloads.example.org/v2.tar.gz', asc: 'https://downloads.example.org/v2.tar.gz.asc', sha512: 'https://downloads.example.org/v2.tar.gz.sha512'}],
}, {
version: 'v1.0.0', latest: false,
@@ -26,20 +23,20 @@ function fixture() {
}],
showcase: {
name: 'Showcase', user: 'apache', repo: 'example-showcase', repoUrl: 'https://github.com/apache/example-showcase.git',
- description: 'Runnable demo.', next: {docs: {link: '/docs/example-showcase/next/readme/', label: 'Showcase for v11'}},
+ description: 'Runnable demo.', docs: {link: '/docs/example-showcase/next/readme/', label: 'Showcase for v11'},
},
};
}
function project(config) { return config.catalogs[0].projects[0]; }
-test('preserves the complete docs URL set, labels, order and intentionally different commit pins', () => {
+test('preserves the complete docs URL set, labels and order, with Latest on the latest release pin', () => {
const config = validateProjectConfig(fixture());
const groups = deriveDocsList(config);
assert.deepEqual(groups[0].list[0].docs, [{version: 'Next', link: '/docs/example-showcase/next/readme/', versionName: 'Showcase for v11'}]);
assert.deepEqual(groups[1].list[1].docs, [
{version: 'Next', link: '/docs/example/next/readme/', commitId: 'main', versionName: 'Development'},
- {version: 'Latest', link: '/docs/example/latest/readme/', commitId: 'latest-docs-fix-pin'},
+ {version: 'Latest', link: '/docs/example/latest/readme/', commitId: 'release-pin'},
{version: 'v2.0.0', link: '/docs/example/v2.0.0/readme/', commitId: 'release-pin', versionName: '2.0.0 (Platform 11)'},
{version: 'v1.0.0', link: '/docs/example/v1.0.0/readme/', commitId: 'old-release-pin'},
]);
@@ -54,12 +51,12 @@ test('a release addition updates the generated Latest entry without a separate L
item.releases[0].latest = false;
item.releases.unshift({
version: 'v3.0.0', latest: true,
- docs: {link: '/docs/example/v3.0.0/readme/', commitId: 'new-release-pin', latestLink: '/docs/example/latest/readme/', latestCommitId: 'new-latest-docs-pin'},
+ docs: {link: '/docs/example/v3.0.0/readme/', commitId: 'new-release-pin'},
});
validateProjectConfig(config);
const docs = docsForProject(item);
assert.equal(docs.filter(doc => doc.version === 'Latest').length, 1);
- assert.equal(docs.find(doc => doc.version === 'Latest').commitId, 'new-latest-docs-pin');
+ assert.equal(docs.find(doc => doc.version === 'Latest').commitId, 'new-release-pin');
assert.equal(docs.find(doc => doc.version === 'v3.0.0').commitId, 'new-release-pin');
assert.deepEqual(docs.map(doc => doc.link).sort(), [...previousUrls, '/docs/example/v3.0.0/readme/'].sort());
assert.equal(item.releases.some(release => release.version === 'Latest'), false);
@@ -69,23 +66,27 @@ test('preserves external versioned docs without inventing a Latest alias', () =>
const config = fixture();
const item = project(config);
delete item.repoUrl;
- delete item.next;
+ delete item.docs;
item.releases = [{version: 'v1.0.0', latest: true, docs: {link: 'https://github.com/apache/example/tree/v1.0.0'}}];
validateProjectConfig(config);
assert.deepEqual(docsForProject(item), [{version: 'v1.0.0', link: 'https://github.com/apache/example/tree/v1.0.0'}]);
});
-test('requires an explicit Latest pin and accepts intentional differences from versioned pins', () => {
+test('serves Latest from the latest release pin, and rejects the retired per-release Latest keys', () => {
const config = fixture();
assert.doesNotThrow(() => validateProjectConfig(config));
+ // Latest renders the pin of the release marked latest, so it cannot be missing.
delete project(config).releases[0].docs.commitId;
- const docs = docsForProject(config.catalogs[0].projects[0]);
- assert.equal(docs.find(doc => doc.version === 'Latest').commitId, 'latest-docs-fix-pin');
- assert.equal(Object.hasOwn(docs.find(doc => doc.version === 'v2.0.0'), 'commitId'), false);
assert.throws(() => validateProjectConfig(config), /requires an explicit documentation commitId/);
project(config).releases[0].docs.commitId = 'release-pin';
- delete project(config).releases[0].docs.latestCommitId;
- assert.throws(() => validateProjectConfig(config), /latestLink requires an explicit latestCommitId/);
+ for (const field of ['latestLink', 'latestCommitId']) {
+ const stale = fixture();
+ project(stale).releases[0].docs[field] = '/docs/example/latest/readme/';
+ assert.throws(() => validateProjectConfig(stale), new RegExp(`docs\\.${field} is gone`));
+ }
+ const elsewhere = fixture();
+ project(elsewhere).docs.latest = '/docs/other/latest/readme/';
+ assert.throws(() => validateProjectConfig(elsewhere), /must serve the same documentation/);
});
test('rejects missing or multiple latest releases', () => {