diff --git a/CLAUDE.md b/CLAUDE.md index 806dd31160e1d..5aa4b1aca34ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,7 +32,11 @@ downloads, and container images. Its structure is `catalogs[]` → `projects[]` `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. +existing `downloadAliases` stable. An entry with `partOf: ` (no `repo`, +`user`, releases or images) is a capability of that project, such as OpenTelemetry +(OTLP) of `skywalking`: one card with a single `docs.link` into that project's +documentation or an HTTP(S) URL, linking to its repository, counted in no +repository inventory. `dockerImages` belongs to the project, alongside `releases`. Each item has `name` and `link`, with optional presentation metadata. These links point to Docker Hub diff --git a/README.md b/README.md index 287a078f4e836..a01c5867f3c7b 100755 --- a/README.md +++ b/README.md @@ -31,6 +31,13 @@ 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. +An entry with `partOf: ` instead of `repo` and `user` is one capability of +that project, such as OpenTelemetry (OTLP) of the main repository. Its card links +to that project's GitHub repository and to a single `docs.link`: a page inside that +project's documentation, or an HTTP(S) URL. It has no releases, images or doc +pins of its own, and counts no stars, contributors, documentation builds or +downloads. It can have a `menu` shortcut. + 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 diff --git a/assets/scss/_custom_home.scss b/assets/scss/_custom_home.scss index 5f0a872c65c8e..e1e29672daaeb 100644 --- a/assets/scss/_custom_home.scss +++ b/assets/scss/_custom_home.scss @@ -120,7 +120,7 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); .pillar-topics { display: flex; flex-wrap: wrap; gap: 7px 14px; margin: 18px 0 0; color: var(--pillar-accent); font-size: 11px; font-weight: 600; line-height: 1.5; } .pillar-topics li + li::before { content: "·"; margin-right: 14px; color: #a2b0be; } .pillar-product { margin-top: auto; border-top: 1px solid #e7ecf2; background: #f7f9fc; } - .pillar-tabs { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); align-items: center; gap: 5px; max-width: 350px; padding: 8px 16px; } + .pillar-tabs { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); align-items: center; gap: 5px; max-width: 470px; padding: 8px 16px; } .pillar-cloud .pillar-tabs { grid-template-columns: repeat(6, minmax(0, 1fr)); max-width: none; } .pillar-tabs button { appearance: none; -webkit-appearance: none; padding: 7px 6px; min-height: 34px; border: 1px solid transparent; border-radius: 6px; background: transparent; color: #67788a; font-family: inherit; font-size: 12px; font-weight: 600; line-height: 1.3; white-space: nowrap; cursor: pointer; } .pillar-tabs button:hover { color: var(--pillar-accent); background: #fff; } @@ -132,8 +132,8 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); .pillar-screen figcaption a { flex-shrink: 0; color: #526b82; text-decoration: none; &:hover { color: var(--pillar-accent); text-decoration: underline; } } .pillar-footer { padding: 18px 28px 24px; border-top: 1px solid #e7ecf2; } .pillar-note { display: flex; align-items: baseline; gap: 7px; min-height: 3.2em; margin: 0 0 16px; color: #6a7b8d; font-size: 11px; line-height: 1.6; } - .pillar-preview { display: inline-block; flex-shrink: 0; padding: 1px 6px; border-radius: 4px; background: var(--pillar-tint); color: var(--pillar-accent); font-size: 10px; font-weight: 650; } .pillar-links { display: flex; align-items: center; justify-content: space-between; gap: 12px; } + .pillar-doc-links { display: inline-flex; flex-wrap: wrap; align-items: center; gap: 4px 16px; } .pillar-cta { display: inline-flex; align-items: center; gap: 12px; color: var(--pillar-accent); font-size: 14px; font-weight: 700; text-decoration: none; &:hover { color: var(--pillar-accent); text-decoration: underline; } } .pillar-docs { color: #657789; font-size: 11px; text-decoration: none; white-space: nowrap; &:hover { color: var(--pillar-accent); text-decoration: underline; } } @@ -159,8 +159,7 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); .ai-domain-heading { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); align-items: end; gap: 60px; margin-bottom: 32px; h2 { margin-bottom: 0; } } .ai-domain-intro p { margin: 0 0 14px; color: #637184; font-size: 15px; line-height: 1.75; } .workflow-heading { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; margin: 0 0 14px; color: #6b567f; font-size: 12px; font-weight: 650; } - .workflow-preview { display: inline-block; padding: 3px 7px; border: 1px solid #e7dcf0; border-radius: 5px; background: #f2eaf9; color: #8454a7; font-size: 10px; font-weight: 650; line-height: 1.3; } - .agent-workflow { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 16px; margin: 0; padding: 0; list-style: none; } + .agent-workflow { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: 16px; margin: 0; padding: 0; list-style: none; } .agent-workflow li { min-width: 0; } .agent-workflow a { display: flex; flex-direction: column; height: 100%; min-height: 220px; padding: 22px; border: 1px solid #e6dcee; border-radius: 12px; background: #fff; text-decoration: none; box-shadow: 0 8px 24px -22px rgba(82, 49, 103, .4); &:hover { border-color: #b894d4; background: #fefcff; } } .workflow-step { display: flex; align-items: center; justify-content: space-between; color: #9d7fb4; font-size: 12px; font-weight: 650; letter-spacing: .05em; > span { font-size: 18px; font-weight: 400; } } @@ -334,6 +333,7 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); } @media (max-width: 576px) { .td-home .pillar-cloud .pillar-tabs { grid-template-columns: repeat(3, minmax(0, 1fr)); } + .td-home .pillar-ai .pillar-tabs { grid-template-columns: repeat(2, minmax(0, 1fr)); } } @media (max-width: 480px) { .td-home { @@ -380,6 +380,7 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); .home-domain h2 { font-size: 31px; } .ai-domain-heading { gap: 30px; } .agent-workflow { grid-template-columns: repeat(2, minmax(0, 1fr)); } + .agent-workflow li:last-child:nth-child(odd) { grid-column: 1 / -1; } .agent-workflow a { min-height: 190px; } .investigation-copy, .investigation-footer { padding-left: 22px; padding-right: 22px; } .investigation-copy h3 { font-size: 22px; } @@ -403,6 +404,7 @@ $brand-grad: linear-gradient(180deg, #479EEB 0%, #3788D0 100%); .td-home { .home-domain > .container, .home-investigation > .container { padding-left: 20px; padding-right: 20px; } .home-domain h2 { font-size: 27px; } + // The headings keep a space before each
, so the words stay apart once it is hidden. .home-domain h2 br { display: none; } .domain-story > p, .ai-domain-intro p { font-size: 14px; } .agent-workflow { grid-template-columns: minmax(0, 1fr); gap: 12px; } diff --git a/assets/scss/_home_platform.scss b/assets/scss/_home_platform.scss index 635e7434c0806..df9766cb08814 100644 --- a/assets/scss/_home_platform.scss +++ b/assets/scss/_home_platform.scss @@ -24,7 +24,7 @@ .hp-group-heading h3 { padding: 0; border: 0; margin: 0 0 6px; color: var(--hp-accent); font-size: 21px; font-weight: 700; line-height: 1.25; } .hp-group-heading p { margin: 0; color: #62758a; font-size: 13px; line-height: 1.6; } .hp-projects { - display: grid; grid-template-rows: 1fr 1.4fr 1.25fr; flex: 1; + display: grid; grid-template-rows: repeat(3, 1fr); flex: 1; padding: 0; margin: 22px 0 0; list-style: none; > li { display: flex; min-width: 0; border-top: 1px solid var(--hp-border); } } @@ -37,7 +37,6 @@ .hp-projects > .hp-integrations { display: flex; flex-direction: column; justify-content: center; padding: 18px 0; &:last-child { padding-bottom: 0; } } .hp-integration-links { display: flex; flex-wrap: wrap; gap: 4px 20px; margin-top: 6px; } .hp-integration-links a { display: inline-flex; align-items: center; gap: 7px; min-height: 32px; color: var(--hp-accent); font-size: 12px; font-weight: 600; text-decoration: none; &:hover { text-decoration: underline; text-underline-offset: 3px; } } - .hp-preview { display: inline-block; margin-left: 6px; padding: 1px 6px; border-radius: 4px; background: var(--hp-tint); color: var(--hp-accent); font-size: 10px; font-weight: 650; vertical-align: 2px; } .hp-shared { margin-top: 18px; padding: 20px 24px; border: 1px solid #e3eaf2; border-radius: 14px; background: #f8fafd; } .hp-shared-heading { display: flex; align-items: baseline; justify-content: space-between; gap: 10px; margin-bottom: 16px; } diff --git a/assets/scss/_showcase_diagram.scss b/assets/scss/_showcase_diagram.scss index 098ccfcb9d5de..43d5097dc15fd 100644 --- a/assets/scss/_showcase_diagram.scss +++ b/assets/scss/_showcase_diagram.scss @@ -52,7 +52,7 @@ &[data-kind="database"] { --sd-accent: #2f866b; --sd-tint: #eaf6f0; } &[data-kind="messaging"] { --sd-accent: #b17a2a; --sd-tint: #fcf4e8; } &[data-kind="traffic"] { --sd-accent: #708294; --sd-tint: #eff3f7; } - &[data-kind="agent"] { --sd-accent: #2875b9; --sd-tint: #e7f3fd; } + &[data-kind="instrumentation"] { --sd-accent: #2875b9; --sd-tint: #e7f3fd; } &[data-kind="integration"] { --sd-accent: #8663ac; --sd-tint: #f3edf9; } &[data-kind="observability"] { --sd-accent: #2875b9; --sd-tint: #e7f3fd; border-color: #aacde8; background: #f5faff; } } diff --git a/content/_index.html b/content/_index.html index ebe5d15cd23c8..8d181f58b6dfa 100644 --- a/content/_index.html +++ b/content/_index.html @@ -5,7 +5,7 @@ seo_title = "Apache SkyWalking — Observability for cloud-native and AI" # Required: without it Hugo's opengraph template falls back to .Summary, which # scrapes the hero SVG text into every social card. -description = "Apache SkyWalking is an open source observability platform for cloud-native systems and AI. Explore services, Kubernetes, and infrastructure with traces, metrics, logs, and profiling; monitor model performance and token usage, and preview Claude Code conversation replay and workspace changes. Investigate through Horizon or your connected AI client." +description = "Apache SkyWalking is an open source observability platform for cloud-native systems and AI. Explore services, Kubernetes, and infrastructure with traces, metrics, logs, and profiling, and trace applications with SkyWalking agents or OpenTelemetry; measure model calls, token usage, and answer quality; replay agent conversations from Claude Code, Kiro, and LangChain, and judge whether the work met its goals. Investigate through Horizon or your connected AI client." +++ @@ -73,7 +73,7 @@

Understand your
running systems.

@@ -81,14 +81,15 @@

Understand your
running systems.

AI observability

Understand model calls
and agent work.

-

Watch model and MCP calls through a gateway: latency and token rates, by provider and model. Or read the agent's own history with AI Sessionizer: conversations, tool calls, and file changes.

-
  • Models & tokens
  • Conversations & tools
  • Workspace changes
+

Measure model calls from GenAI traces or a gateway, and score traced answers with an LLM judge. Read the agent's own history with AI Sessionizer: conversations, tool calls, file changes, and whether the work met its goals.

+
  • Models, tokens & quality
  • Conversations & tools
  • Changes & outcomes
Claude Code conversation replay with its timeline and recorded workspace changes @@ -102,10 +103,14 @@

Understand model calls
and agent work.

SkyWalking AI Agent Overview with token heatmaps and usage by agent
See when and where tokens are usedEnlarge
+
@@ -128,7 +133,7 @@

Understand model calls
and agent work.

CLOUD-NATIVE OBSERVABILITY -

See your systems
in context.

+

See your systems
in context.

Explore services and Kubernetes infrastructure together. Follow dependencies, rotate the 3D scene, and select a node to inspect it.

  • Service relationships
  • Infrastructure topology
  • Interactive exploration
Explore the 3D map @@ -141,10 +146,10 @@

See your systems
in context.

-
AI OBSERVABILITY

From model performance
to agent work.

-

Two vantage points. AI Sessionizer reads the agent's own history, so you can explore usage, replay conversations, and inspect the work recorded inside them — that is what the workflow below shows. A gateway sees model and MCP calls as traffic, with latency, token rates, and streaming timings broken down by provider and model.

+
AI OBSERVABILITY

From model performance
to agent work.

+

Three vantage points. AI Sessionizer reads the agent's own history: explore usage, replay conversations, inspect the recorded work, and judge whether it met its goals, as the workflow below shows. GenAI traces from SkyWalking agents or OpenTelemetry measure each model call, and an LLM judge can score its answers. A gateway sees model and MCP calls as traffic, with latency, token rates, and streaming timings by provider and model.

-
Inside a Claude Code workflow, via AI SessionizerPreview
+
Inside an agent's work, via AI Sessionizer
{{< home-agent-workflow >}}
diff --git a/content/images/project/otlp.svg b/content/images/project/otlp.svg new file mode 100644 index 0000000000000..75127fa880beb --- /dev/null +++ b/content/images/project/otlp.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/data/blog_topics.yml b/data/blog_topics.yml index ed489be59ae91..968e8624e999f 100644 --- a/data/blog_topics.yml +++ b/data/blog_topics.yml @@ -6,7 +6,7 @@ # .blog-label[data-label="X"] # color rules at build time # -# To add a 12th topic: append an entry here, then use that exact `name` as a +# To add a 13th topic: append an entry here, then use that exact `name` as a # tag in any blog post's frontmatter. No template / SCSS changes required. # # Field reference: @@ -32,6 +32,11 @@ topics: intro_zh: 分布式追踪、OpenTelemetry、Zipkin 与 TraceQL。 color: { bg: "#fdecde", fg: "#c2580d", border: "#f6d4ba" } + - name: OpenTelemetry + intro: OpenTelemetry traces, metrics and logs over OTLP — native storage, analysis and topology. + intro_zh: 通过 OTLP 接入 OpenTelemetry 的链路、指标与日志:原生存储、分析与拓扑。 + color: { bg: "#fdf6d8", fg: "#8a5a00", border: "#f4e4a8" } + - name: Metrics intro: MAL, PromQL, dashboards and Grafana integrations. intro_zh: MAL、PromQL、仪表盘与 Grafana 集成。 diff --git a/data/get-started.yml b/data/get-started.yml index ec7f4e70c6d4e..b0d2e99d575a3 100644 --- a/data/get-started.yml +++ b/data/get-started.yml @@ -184,38 +184,38 @@ showcase: to: activemq - id: telemetry label: Observability stack - description: Native agents and ecosystem integrations feed OAP. Showcase's monitoring collectors use OTLP metrics; its Kubernetes mesh scenario adds ALS access logs and Zipkin traces. + description: SkyWalking agents and OpenTelemetry both instrument applications for OAP, which analyzes their traces into the same metrics and topology. Showcase's collectors also send OTLP metrics; its Kubernetes mesh scenario adds ALS access logs and sidecar traces. columns: 3 rows: 4 nodes: - id: instrumented-app title: Instrumented app subtitle: SkyWalking agents - kind: agent + kind: instrumentation column: 1 row: 1 description: Agents instrument the music application and report telemetry to OAP. These signals connect requests across the different services. - id: otlp title: OpenTelemetry - subtitle: OTLP ecosystem - kind: integration + subtitle: OTLP traces, metrics & logs + kind: instrumentation column: 1 row: 2 - description: Showcase uses OpenTelemetry Collectors to scrape infrastructure, database, and messaging metrics and send them to OAP over OTLP. OAP also accepts OTLP traces and logs from compatible SDKs and collectors when their receivers are enabled; these are additional integration options. + description: OpenTelemetry agents, SDKs, and proxies or frameworks with built-in OTLP tracing send traces to OAP, which stores them as they arrive. With one resource attribute set, OAP analyzes them into the same service metrics and topology as SkyWalking agents' traces. Showcase's OpenTelemetry tracing scenario runs the OpenTelemetry Astronomy Shop this way, and its OpenTelemetry Collectors scrape infrastructure, database, and messaging metrics and send them over OTLP. - id: istio-envoy title: Istio / Envoy subtitle: Access Log Service kind: integration column: 1 row: 3 - description: The Kubernetes mesh scenario sends Envoy HTTP and TCP access logs through ALS. OAP derives service topology and metrics without application agents. ALS is a service mesh integration, separate from trace collection; Satellite can relay its data to OAP when selected. + description: The Kubernetes mesh scenario sends Envoy HTTP and TCP access logs through ALS, and traces its sidecars over OTLP. OAP derives service topology and metrics without application agents. ALS is a service mesh integration, separate from trace collection; Satellite can relay its data to OAP when selected. - id: zipkin title: Zipkin ecosystem subtitle: Compatible tracers kind: integration column: 1 row: 4 - description: Zipkin-compatible tracers send spans directly to OAP. Showcase's Kubernetes mesh scenario uses Envoy's Zipkin exporter for this path, alongside ALS access logs. OAP provides the trace receiver and query APIs, so no separate Zipkin server is required. + description: Zipkin-compatible tracers send spans directly to OAP. OAP provides the trace receiver and query APIs, so no separate Zipkin server is required. - id: oap title: SkyWalking OAP subtitle: Analyze telemetry @@ -244,7 +244,7 @@ showcase: label: Native telemetry - from: otlp to: oap - label: OTLP metrics + label: OTLP traces & metrics - from: istio-envoy to: oap label: ALS access logs @@ -259,8 +259,10 @@ showcase: to: oap label: Query scenarios: + - title: OpenTelemetry tracing + description: The OpenTelemetry Astronomy Shop traced over OTLP, with service metrics, topology, database, cache, and MQ dashboards, and TraceQL search. On Docker, six more topology cases cover gateways, canaries, queues, and databases. - title: Service mesh & networking - description: Istio / Envoy ALS access log analysis and Zipkin tracing, services with agents in a mesh, and Cilium service traffic. + description: Istio / Envoy ALS access log analysis and sidecar tracing over OTLP, services with agents in a mesh, and Cilium service traffic. platform: Kubernetes - title: Profiling description: Java and Python trace profiling, plus Rover for eBPF process discovery. @@ -272,7 +274,7 @@ showcase: - title: Infrastructure & events description: Metrics from simulated hosts, Kubernetes monitoring and events, and SkyWalking self-observability. - title: Collection & visualization - description: Satellite for telemetry load balancing, and Grafana for metrics and logs. + description: Satellite for telemetry load balancing, and Grafana for metrics, logs, and TraceQL trace search. - title: More analysis description: Flink monitoring, R3 URL recognition, and SkyPredictor metric baselines. R3 and SkyPredictor run on Kubernetes. diff --git a/data/projects.yml b/data/projects.yml index 64ddf2a176356..4983687b2c0cf 100644 --- a/data/projects.yml +++ b/data/projects.yml @@ -1142,6 +1142,17 @@ catalogs: date: Jan. 9th, 2022 downloadAliases: - KongAgent + - name: OpenTelemetry (OTLP) + partOf: skywalking + icon: otlp + description: Send traces, metrics, and logs from OpenTelemetry agents, SDKs, and built-in OTLP exporters. Set `service.layer=OTLP_GENERAL`, and OTLP traces get service metrics and topology, named and counted like those of SkyWalking agents' traces. + menu: + group: Agents & collection + column: 1 + order: 0 + description: OTLP traces, metrics, and logs + docs: + link: /docs/main/latest/en/setup/backend/otlp-trace/ - name: SkyWalking Satellite repo: skywalking-satellite user: apache @@ -1151,7 +1162,7 @@ catalogs: menu: group: Agents & collection column: 1 - order: 1 + order: 2 description: Lightweight telemetry collector docs: link: /docs/skywalking-satellite/next/readme/ @@ -1191,7 +1202,7 @@ catalogs: menu: group: Agents & collection column: 1 - order: 2 + order: 3 description: Kubernetes event collection docs: link: https://github.com/apache/skywalking-kubernetes-event-exporter/tree/main#configurations @@ -1230,7 +1241,7 @@ catalogs: menu: group: Agents & collection column: 1 - order: 0 + order: 1 description: eBPF metrics and profiling docs: link: /docs/skywalking-rover/next/readme/ diff --git a/layouts/docs/baseof.html b/layouts/docs/baseof.html index 9f7eb93d8b9dd..018055fc9bba3 100644 --- a/layouts/docs/baseof.html +++ b/layouts/docs/baseof.html @@ -80,7 +80,7 @@

{{ .title }}

{{ with .data.note }}
{{ . | markdownify }}
{{ end }}
{{ range .data.projects }} - {{ with index $catalog (.repo | default "") }} + {{ with index $catalog (partial "project-key.html" .) }} {{ partial "project-card.html" (dict "Entry" . "Category" (printf "%s %s" $category.title $category.data.name) "Site" $.Site) }} {{ end }} {{ end }} diff --git a/layouts/downloads/baseof.html b/layouts/downloads/baseof.html index 4deba4bc47572..975851df7dbd4 100644 --- a/layouts/downloads/baseof.html +++ b/layouts/downloads/baseof.html @@ -4,7 +4,7 @@ {{ range .Site.Data.projects.catalogs }} {{ $entries := slice }} {{ range .projects }} - {{ with index $catalog .repo }}{{ if or .downloads .images }}{{ $entries = $entries | append . }}{{ end }}{{ end }} + {{ with index $catalog (partial "project-key.html" .) }}{{ if or .downloads .images }}{{ $entries = $entries | append . }}{{ end }}{{ end }} {{ end }} {{ if $entries }}{{ $groups = $groups | append (dict "id" .id "title" .name "entries" $entries) }}{{ end }} {{ end }} diff --git a/layouts/partials/project-card.html b/layouts/partials/project-card.html index 255ae0c648ff7..80b19b4304539 100644 --- a/layouts/partials/project-card.html +++ b/layouts/partials/project-card.html @@ -1,6 +1,7 @@ {{ $project := .Entry.project }} {{ $id := replaceRE `[ ()]` "" $project.name }} -{{ $stars := index .Site.Data.stars.repos (printf "%s/%s" $project.user $project.repo) }} +{{ $stars := "" }} +{{ if not .Entry.partOf }}{{ $stars = index .Site.Data.stars.repos (printf "%s/%s" $project.user $project.repo) }}{{ end }}
{{ with $project.icon }}{{ end }} @@ -12,7 +13,7 @@

{{ $project.name }}

{{ $project.description | markdownify }}
{{ partial "project-documentation.html" (dict "Entry" .Entry "Context" "catalog") }}
@@ -51,22 +53,26 @@

Build your observability stack.

@@ -77,7 +83,7 @@

Build your observability stack.

{{- range slice (dict "repo" "skywalking-horizon-ui" "label" "Horizon UI" "description" "Explore and investigate.") - (dict "repo" "skywalking" "label" "Observability Analysis Platform" "description" "Analyze and correlate.") + (dict "repo" "skywalking" "label" "Observability Analysis Platform" "description" "Complete analysis and correlation.") (dict "repo" "skywalking-banyandb" "label" "BanyanDB" "description" "Store and query telemetry.") -}} {{- $project := (index $catalog .repo).project -}} diff --git a/scripts/project-config.js b/scripts/project-config.js index 46880a2322fb9..eee74d822fdcd 100644 --- a/scripts/project-config.js +++ b/scripts/project-config.js @@ -28,6 +28,7 @@ function validateProjectConfig(config) { const catalogIds = new Set(); const repos = new Set(); const localDocs = new Set(); + const parts = new Map(); function validateDocs(docs, project, version, where) { check(isObject(docs), `${where} must be an object`); @@ -45,8 +46,27 @@ function validateProjectConfig(config) { if (docs.label !== undefined) check(isText(docs.label), `${where}.label must be a nonempty string`); } + // An entry that is part of another project (`partOf`), such as one capability of the main + // repository, has a card and a single docs link. It links to that project's repository and has + // no repository, releases or images of its own, so stars, contributors, documentation builds + // and downloads never count it twice. + function validatePart(project, where) { + ['name', 'description'].forEach(field => check(isText(project[field]), `${where}.${field} must be a nonempty string`)); + check(isText(project.partOf) && /^[a-z0-9_.-]+$/i.test(project.partOf), `${where}.partOf must be a repository name`); + ['user', 'repo', 'repoUrl', 'archive', 'extraContributors', 'featured', 'releases', 'dockerImages', 'downloadAliases'].forEach(field => + check(project[field] === undefined, `${where}.${field} is not allowed on an entry that is part of ${project.partOf}`)); + const key = `${project.partOf}/${project.name}`.toLowerCase(); + check(!parts.has(key), `duplicate entry ${project.name} in ${project.partOf}`); + parts.set(key, {project, where}); + check(isObject(project.docs), `${where}.docs must be an object`); + const link = project.docs.link; + check(isWebLink(link) || (typeof link === 'string' && /^\/docs\/[^/?#\s]+\/[^?#\s]*\/$/.test(link)), `${where}.docs.link must be a /docs/ path ending in / or an HTTP(S) URL`); + ['latest', 'commitId', 'label'].forEach(field => check(project.docs[field] === undefined, `${where}.docs.${field} is not allowed: the entry has one docs link`)); + } + function validateProject(project, where) { check(isObject(project), `${where} must be an object`); + if (project.partOf !== undefined) return validatePart(project, where); ['name', 'repo', 'user', 'description'].forEach(field => check(isText(project[field]), `${where}.${field} must be a nonempty string`)); check(/^[a-z0-9_.-]+$/i.test(project.repo), `${where}.repo must be a repository name`); check(/^[a-z0-9_-]+$/i.test(project.user), `${where}.user must be a GitHub owner`); @@ -124,6 +144,18 @@ function validateProjectConfig(config) { check(Array.isArray(catalog.projects), `${where}.projects must be an array`); catalog.projects.forEach((project, projectIndex) => validateProject(project, `${where}.projects[${projectIndex}]`)); }); + const owners = config.catalogs.flatMap(catalog => catalog.projects).filter(project => project.partOf === undefined); + parts.forEach(({project, where}) => { + // Exact spelling: the site looks the parent up by its repo, case-sensitively. + const parent = owners.find(owner => owner.repo === project.partOf); + check(parent, `${where}.partOf names no project with repo ${project.partOf}`); + if (project.docs.link.startsWith('/')) { + const parentLink = parent.docs && typeof parent.docs.link === 'string' ? parent.docs.link : ''; + // Normalized, so a `..` segment cannot leave the parent's documentation. + const partPath = new URL(project.docs.link, 'https://skywalking.apache.org').pathname; + check(parentLink.startsWith('/docs/') && partPath.startsWith(`/docs/${parentLink.split('/')[2]}/`), `${where}.docs.link must be in the documentation of ${project.partOf}`); + } + }); validateProject(config.showcase, 'showcase'); if (config.website) validateProject(config.website, 'website'); return config; @@ -212,7 +244,8 @@ function deriveDocsList(config) { const quickStart = {type: 'Quick Start', buttonText: 'Showcase', list: [docsProject(config.showcase)]}; if (config.website) quickStart.list.push(docsProject(config.website)); return [quickStart, ...config.catalogs.map(catalog => { - const group = {type: catalog.name, list: catalog.projects.map(docsProject)}; + // An entry that is part of another project builds no docs and counts no repository. + const group = {type: catalog.name, list: catalog.projects.filter(project => project.partOf === undefined).map(docsProject)}; if (catalog.description !== undefined) group.description = catalog.description; if (catalog.buttonText !== undefined) group.buttonText = catalog.buttonText; if (catalog.note) group.list.unshift({name: null, descriptionItem: catalog.note}); diff --git a/scripts/project-config.test.js b/scripts/project-config.test.js index e4b3464e3f4d3..a6bc19232e50e 100644 --- a/scripts/project-config.test.js +++ b/scripts/project-config.test.js @@ -163,6 +163,29 @@ test('includes Showcase and package-derived Website in the team/stars repository }); }); +test('an entry that is part of another project links into its docs and is not counted as a repository', () => { + const config = fixture(); + const part = {name: 'Example Feature', partOf: 'example', description: 'One capability of Example.', docs: {link: '/docs/example/latest/en/feature/'}}; + config.catalogs.push({id: 'features', name: 'Features', projects: [part]}); + validateProjectConfig(config); + assert.deepEqual(collectRepos(config), [{user: 'apache', repo: 'example-showcase'}, {user: 'apache', repo: 'example'}]); + assert.deepEqual(deriveDocsList(config)[2].list, []); + const variant = change => { const c = fixture(); c.catalogs.push({id: 'features', name: 'Features', projects: [{...part, ...change}]}); return c; }; + validateProjectConfig(variant({docs: {link: 'https://example.org/feature'}})); + assert.throws(() => validateProjectConfig(variant({partOf: 'missing'})), /names no project with repo missing/); + assert.throws(() => validateProjectConfig(variant({partOf: 'Example'})), /names no project with repo Example/); + assert.throws(() => validateProjectConfig(variant({docs: {link: '/docs/example/../other/latest/readme/'}})), /in the documentation of example/); + assert.throws(() => validateProjectConfig(variant({docs: {link: '/docs/example/../../blog/example/feature/'}})), /in the documentation of example/); + assert.throws(() => validateProjectConfig(variant({repo: 'example'})), /repo is not allowed on an entry that is part of example/); + assert.throws(() => validateProjectConfig(variant({releases: []})), /releases is not allowed/); + assert.throws(() => validateProjectConfig(variant({docs: {link: '/docs/other/latest/en/feature/'}})), /in the documentation of example/); + assert.throws(() => validateProjectConfig(variant({docs: {link: '/docs/example/latest/en/feature'}})), /ending in \//); + assert.throws(() => validateProjectConfig(variant({docs: {link: '/docs/example/latest/en/feature/', commitId: 'pin'}})), /docs\.commitId is not allowed/); + const twice = fixture(); + twice.catalogs.push({id: 'features', name: 'Features', projects: [part, {...part}]}); + assert.throws(() => validateProjectConfig(twice), /duplicate entry Example Feature in example/); +}); + test('the repository catalog lists every repository of the site exactly once', () => { const config = validateProjectConfig(fixture()); const catalog = repos => ({categories: [{id: 'main', name: 'Main', repos}]});