diff --git a/.agents/skills/signoz-docs-pr-review/SKILL.md b/.agents/skills/signoz-docs-pr-review/SKILL.md index 6e27e58f67..da0ea7d39f 100644 --- a/.agents/skills/signoz-docs-pr-review/SKILL.md +++ b/.agents/skills/signoz-docs-pr-review/SKILL.md @@ -1,6 +1,6 @@ --- name: signoz-docs-pr-review -description: Review SigNoz documentation pull requests using CONTRIBUTING.md and this skill's docs-review rubric. Use when asked to review docs PRs, post inline findings, verify OpenTelemetry technical accuracy with sources, decide add-to-onboarding labeling, and write a concise checklist-based summary. +description: Review SigNoz documentation pull requests — post inline findings, verify OpenTelemetry technical accuracy with sources, decide add-to-onboarding labeling, and write a concise checklist-based summary. Use when asked to review docs PRs, check documentation changes, evaluate MDX content in data/docs, or assess any docs-related PR, even when the user just says "review this PR" and the changed files are documentation. --- # SigNoz Docs PR Review @@ -21,108 +21,23 @@ If a PR includes frontend code too, use this skill only for the docs part. ## Source of Truth -- Treat `CONTRIBUTING.md` at repo root as the single source of truth for docs standards. -- Apply rules; do not restate the entire guide in comments. -- Ignore date-related guideline checks during review. +The review standards live in the `contributing/` playbooks, not in this skill file. This skill orchestrates the review process; the playbooks define the policy. + +- `contributing/docs-review.md` — review rubric, JTBD checklist, technical accuracy rules, onboarding-label policy, summary format +- `contributing/docs-authoring.md` — authoring standards, frontmatter rules, page structure, doc-type guidance, author checklist + +Apply rules from those playbooks directly. Do not restate the entire guide in comments. Ignore date-related guideline checks during review. ## Review Process 1. Identify docs files changed in the PR. 2. Identify related discoverability files that should change with the docs when relevant (`constants/docsSideNav.ts` for sidebar visibility, `constants/componentItems.ts` as the public entrypoint and `constants/componentItems/*.ts` as the source modules for listicle/overview visibility). -3. Read relevant sections in `CONTRIBUTING.md` (JTBD, patterns/components, happy path, hyperlinks, doc-type rules, docs checklist). +3. **Read `contributing/docs-review.md` and `contributing/docs-authoring.md` in full before starting the review.** These playbooks contain the JTBD rubric, authoring standards, onboarding-label policy, and summary format that drive every review decision. Reviewing without reading them first leads to missed checks and inconsistent feedback. 4. Identify intended user personas for each changed doc (for example: OTel beginner, platform engineer, app developer, SRE) from doc context. -5. Run a **JTBD-first pass** (mandatory) before technical verification. -6. Verify technical accuracy when claims involve OpenTelemetry behavior/configuration. +5. Run the JTBD-first pass defined in `contributing/docs-review.md` before technical verification. +6. Verify technical accuracy when claims involve OpenTelemetry behavior or configuration, following the source priority and citation rules in `contributing/docs-review.md`. 7. Post inline findings for concrete issues. -8. Post exactly one concise summary comment referencing Docs PR Checklist coverage. - -## JTBD Priority Rubric (Mandatory) - -Review each changed doc against these checks in order. If any check fails, raise a finding. - -1. Intended personas - - List primary and secondary personas the doc appears to target. - - Confirm scope, assumptions, and language match those personas. -2. Primary job clarity - - The reader can quickly tell what problem this page solves. - - The page does not mix unrelated jobs into one mandatory flow. -3. Happy/common path focus - - Common path is easy to follow end-to-end. - - Tangential information is minimized or moved to optional/collapsible sections. -4. Time-to-first-success - - A clear default path exists and reaches first success without optional detours. - - Mandatory steps are minimal and in the right order. -5. Step clarity and concision - - Steps are concrete, unambiguous, and concise. - - Users can execute each step without guessing missing actions. -6. Minimal required steps - - The doc requires only what is necessary to complete the primary job. - - Non-essential actions are explicitly optional. -7. Recommended defaults vs advanced options - - Best/recommended configuration is presented as default. - - Advanced options are moved to the bottom, troubleshooting, collapsible sections, or next steps. -8. Beginner unblockers - - Any required attribute/config/concept has a direct "how to set this" step or link to a doc that explains how to set it. - - No critical prerequisite is implied without remediation guidance. -9. Symptom-to-action mapping - - Troubleshooting starts from user-visible symptoms and points to exact next actions. - - Failure modes are concrete (not generic "check your setup"). -10. Success signal - - Validation tells users exactly where to check in SigNoz and what success looks like. -11. Follow-through - - Next steps help users complete the broader job (for example dashboards, alerts, deeper guides). -12. Helpful links (internal/external) - - Link to internal/external docs wherever they directly help completion of the current step. - - Avoid irrelevant link dumping. -13. Link health - - Added/edited links resolve (no dead links). Prefer canonical production paths. -14. Discoverability surface updates - - If a PR adds a new integration, data source, installation path, dashboard template, or similar doc that users should find from an existing docs listicle/overview card surface, verify the matching entry was added or updated in the relevant `constants/componentItems/*.ts` module and remains exported through `constants/componentItems.ts`. - - When the surfaced component uses icons, verify the relevant component `ICON_MAP` was updated too. - - Do not require this when no existing listicle/overview surface is relevant. - -If a JTBD check cannot be validated from the PR context, explicitly call out the assumption and residual risk. - -## Technical Accuracy and Sources - -When validating technical claims, use this source priority: - -1. `https://opentelemetry.io/docs/*` -2. `https://github.com/open-telemetry/*` (official repos, READMEs, examples) -3. Other reputable sources only if official sources do not cover the claim - -For each correction that depends on verification: - -- Add a short citation in the comment as: `Source: ` -- Keep citations precise and relevant to the claim -- Do not paste long excerpts - -Prioritize verification for: - -- Config keys and component names -- Receiver/exporter/processor names -- Environment variables and CLI flags -- APIs, semantic conventions, version compatibility, deprecations - -If sources conflict, prefer the most recent official OpenTelemetry docs/repo over third-party content. - -## Web Lookup Guidance - -- Use targeted queries first (for example, `site:opentelemetry.io `). -- Fetch only the minimal pages needed to verify the exact claim. -- Summarize findings; avoid large copy-paste. - -## Labeling Rule - -If PR adds a **new** docs file (not only edits existing docs) that explains sending data to SigNoz Cloud (for example new instrumentation, new collector receiver flow, or new log collection method), add label: - -- `add-to-onboarding` - -Command: - -```bash -gh issue edit --add-label "add-to-onboarding" -``` +8. Post exactly one concise summary comment using the format in `contributing/docs-review.md`. ## Commenting Rules @@ -149,9 +64,9 @@ Post one summary comment that includes: 1. Key findings grouped by severity (`P1`, `P2`, `P3`) 2. Intended personas and fit summary (who this doc serves and where fit is weak) 3. JTBD coverage summary (which mandatory JTBD checks failed or were at risk) -4. Checklist-oriented coverage summary (what failed/needs work) +4. Checklist coverage summary (what failed or needs work against `contributing/docs-authoring.md`) 5. Any open questions/assumptions -6. Whether onboarding label was applied (when relevant) +6. The onboarding-label result from `contributing/docs-review.md` ## Suggested Commands @@ -159,10 +74,12 @@ Post one summary comment that includes: # PR context gh pr view gh pr diff +gh api repos//pulls//files --paginate -# changed docs and policy anchors +# changed docs and guidance rg --files data/docs -rg -n "JTBD|happy path|Patterns and components|Hyperlinks|Docs PR Checklist" CONTRIBUTING.md +cat contributing/docs-authoring.md +cat contributing/docs-review.md # scan for likely docs quality issues rg -n "## Next steps|## Troubleshooting|KeyPointCallout|ToggleHeading|https?://|<[^>]+>" data/docs @@ -173,8 +90,6 @@ curl -sI ## Guardrails -- Do not require a dedicated "Target Persona" section unless context truly needs it. -- Keep advanced options out of the mandatory path unless essential for first success. -- If a PR adds or changes docs MDX components or component-driven content patterns, verify both agent markdown handling (`utils/docs/agentMarkdownStubs.ts`) and rendered Copy Markdown behavior (`utils/docs/buildCopyMarkdownFromRendered.ts`) where relevant. +- Do not restate large parts of the playbooks in comments. - Keep review feedback decision-oriented and immediately actionable. -- Do not mark a review complete if mandatory JTBD checks were skipped. +- Follow the JTBD, technical verification, and onboarding-label guidance from `contributing/docs-review.md`. diff --git a/.agents/skills/signoz-docs-pr-review/agents/openai.yaml b/.agents/skills/signoz-docs-pr-review/agents/openai.yaml index ef9a361ca6..e952c4dbaa 100644 --- a/.agents/skills/signoz-docs-pr-review/agents/openai.yaml +++ b/.agents/skills/signoz-docs-pr-review/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "SigNoz Docs PR Review" - short_description: "Review SigNoz docs PRs against CONTRIBUTING.md" + short_description: "Review SigNoz docs PRs against the contributing playbooks" default_prompt: "Use $signoz-docs-pr-review to review this docs PR and return prioritized inline findings with a concise checklist summary." diff --git a/.agents/skills/signoz-website-frontend-pr-review/SKILL.md b/.agents/skills/signoz-website-frontend-pr-review/SKILL.md index 2800ceef88..b1ae2af408 100644 --- a/.agents/skills/signoz-website-frontend-pr-review/SKILL.md +++ b/.agents/skills/signoz-website-frontend-pr-review/SKILL.md @@ -1,6 +1,6 @@ --- name: signoz-website-frontend-pr-review -description: Review SigNoz frontend pull requests using this skill's rubric and project-specific standards from CONTRIBUTING.md. Use when asked to review JS/TS/React/Next.js changes for duplication, architecture, App Router best practices, performance, maintainability, and accessibility. +description: Review SigNoz frontend pull requests for duplication, architecture, App Router best practices, performance, maintainability, and accessibility. Use when asked to review JS/TS/React/Next.js changes, check components or hooks, evaluate frontend code quality, or review any PR whose changed files are under app/, components/, hooks/, utils/, or similar frontend paths. --- # SigNoz Frontend PR Review @@ -19,16 +19,16 @@ If a PR includes docs too, use this skill for code review only. ## Source of Truth -- Use this skill file as the frontend review rubric. -- Apply project-specific constraints from `CONTRIBUTING.md` for code standards. +This skill file defines the review rubric (the 13 categories below). Project-specific code conventions and verification commands live in `contributing/site-code.md` — read it before reviewing so you apply the canonical rules, not stale assumptions. ## Review Process 1. Get PR context and changed files. -2. Scan for high-impact issues first (duplication, architecture, performance). -3. Evaluate against the categories below. -4. Leave inline comments for specific issues only. -5. Post exactly one concise summary grouped by severity. +2. **Read `contributing/site-code.md` in full before starting the review.** It contains the project's icon policy, UI primitive expectations, componentItems data placement rules, async/DOM safety rules, MDX rendering constraints, dependency policy, and required verification commands. Reviewing without reading it first leads to missed project-specific findings. +3. Scan for high-impact issues first (duplication, architecture, performance). +4. Evaluate against the categories below. +5. Leave inline comments for specific issues only. +6. Post exactly one concise summary grouped by severity. ## Review Categories @@ -116,19 +116,13 @@ If a PR includes docs too, use this skill for code review only. - Check import order/organization. - Flag circular dependencies. - Avoid duplicate functionality from existing deps. -- Ensure new deps are justified (per `CONTRIBUTING.md`). +- Ensure new deps are justified (per `contributing/site-code.md`). -### 11) Project-specific rules (`CONTRIBUTING.md`) +### 11) Project-specific rules (`contributing/site-code.md`) -- Prefer existing icon libs (`lucide-react`, `react-icons`). -- Prefer existing UI primitives in `components/ui`. -- Keep types/constants co-located and exported appropriately. -- Avoid concurrent async invocations in handlers (loading/ref guards). -- Be deliberate with DOM cleanup/transforms. -- If a PR adds or changes MDX components used in `data/docs/**`, verify `utils/docs/agentMarkdownStubs.ts` still handles them, the agent-markdown tests/coverage remain valid, and rendered Copy Markdown behavior in `utils/docs/buildCopyMarkdownFromRendered.ts` still stays clean. -- Justify dependency additions. -- **Listicle / icon-card items must stay exported through `constants/componentItems.ts` and source data should live in `constants/componentItems/*.ts`**, not inside component files. Flag any `{ name, href, clickName }` arrays defined inline in a component. -- **Never use `slice()` with hardcoded indices to split a flat array into sub-sections.** If a constant has logically distinct sub-groups (for example AWS / Azure / GCP), each group must be a named sub-key (`cloud: { aws: [...], azure: [...], gcp: [...] }`). Adding or removing an item in one group silently shifts slice boundaries in others — flag this pattern as a `High` finding. +- Apply the project-specific rules from `contributing/site-code.md`. +- Pay extra attention to icon usage, existing UI primitives, `constants/componentItems*.ts` data placement, async handler safety, MDX rendering compatibility, and dependency justification. +- Treat hardcoded `slice()` boundaries for logical sub-sections as a `High` finding. ### 12) Error handling and edge cases @@ -181,6 +175,9 @@ Post exactly one concise summary that: gh pr view gh pr diff +# project-specific standards +cat contributing/site-code.md + # find similar code find components shared -name "*.tsx" -type f rg -n "" utils hooks app/lib components shared @@ -195,3 +192,4 @@ rg -n "^import " app components hooks utils shared - For style changes, prefer Tailwind-first implementations and avoid introducing new component-level CSS systems when existing Tailwind patterns already solve the requirement. - Avoid speculative refactors outside PR scope unless there is clear risk reduction. - Keep feedback decision-oriented and implementable without ambiguity. +- Read `contributing/site-code.md` during the review instead of relying on memory or partial summaries. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ae2f3f2ee8..83973d2647 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -57,18 +57,20 @@ If breaking change, describe migration steps: - [ ] Pre-commit hooks passed (or ran `yarn check:doc-redirects` / `yarn check:docs-metadata` if applicable) ### For docs changes (`data/docs/**`) -- [ ] Completed the [Docs PR Checklist](CONTRIBUTING.md#docs-pr-checklist) in CONTRIBUTING.md +- [ ] Followed the docs author checklist in [contributing/docs-authoring.md](https://github.com/SigNoz/signoz.io/blob/main/contributing/docs-authoring.md) - [ ] Added/updated the page in `constants/docsSideNav.ts` if adding or moving a doc ### For blog changes +- [ ] Followed the blog workflow in [contributing/blog-workflow.md](https://github.com/SigNoz/signoz.io/blob/main/contributing/blog-workflow.md) - [ ] Frontmatter includes `title`, `date`, `author`, `tags` (and `canonicalUrl` if applicable) - [ ] Images use WebP format and live under `public/img/blog//` ### For site code changes -- [ ] Follows [Site Code Guidelines](CONTRIBUTING.md#website-code-guidelines) in CONTRIBUTING.md +- [ ] Followed the site code playbook in [contributing/site-code.md](https://github.com/SigNoz/signoz.io/blob/main/contributing/site-code.md) - [ ] New dependencies are justified in the PR description (if any) ### For renamed or moved docs +- [ ] Followed the redirects and discovery section in [contributing/docs-authoring.md](https://github.com/SigNoz/signoz.io/blob/main/contributing/docs-authoring.md) - [ ] Added permanent redirect in `next.config.js` under `async redirects()` - [ ] Updated internal links and sidebar in `constants/docsSideNav.ts` - [ ] Ran `yarn check:doc-redirects` to verify diff --git a/.github/workflows/claude-doc-update.yaml b/.github/workflows/claude-doc-update.yaml index 53bec0c6fd..e1fa34b925 100644 --- a/.github/workflows/claude-doc-update.yaml +++ b/.github/workflows/claude-doc-update.yaml @@ -142,7 +142,7 @@ jobs: Do NOT modify application code. Only add under FAQ if it's brief problem/solution. Else create new page under troubleshooting. - - Follow the repo's CONTRIBUTING.md documentation guidelines. + - Use `CONTRIBUTING.md` as the entrypoint and follow `contributing/docs-authoring.md` for documentation guidance (includes redirects and discovery). - Content placement: - If it's a brief problem/solution, add it under FAQs. - Otherwise, add it under troubleshooting diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 14661dd1eb..99fc9ea912 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -200,9 +200,11 @@ jobs: if: github.event_name == 'pull_request' uses: anthropics/claude-code-action@v1 env: + GH_TOKEN: ${{ steps.mint_identity_token.outputs.token || github.token }} PR_NUMBER: ${{ steps.pr.outputs.number || github.event.pull_request.number || github.event.issue.number }} with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + github_token: ${{ steps.mint_identity_token.outputs.token || github.token }} track_progress: true # ✨ Enables tracking comments prompt: | REPO: ${{ github.repository }} @@ -211,10 +213,12 @@ jobs: Review this pull request and use relevant project skills from `.claude/skills`. - Use `signoz-docs-pr-review` for docs changes. - Use `signoz-website-frontend-pr-review` for frontend code changes. + - Treat `CONTRIBUTING.md` as the entrypoint and `contributing/**` as the detailed policy source. Apply only the relevant skill(s) based on changed files. Leave inline comments for concrete issues and post exactly one concise summary comment. - Do not add praise-only comments. + Do not add praise comments. + For docs PRs, follow the onboarding-label policy and summary format in `contributing/docs-review.md` via the `signoz-docs-pr-review` skill. claude_args: | --model "claude-opus-4-6" @@ -224,10 +228,12 @@ jobs: if: github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' uses: anthropics/claude-code-action@v1 env: + GH_TOKEN: ${{ steps.mint_identity_token.outputs.token || github.token }} PR_NUMBER: ${{ steps.pr.outputs.number || github.event.pull_request.number || github.event.issue.number }} COMMENT_BODY: ${{ github.event.comment.body }} with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + github_token: ${{ steps.mint_identity_token.outputs.token || github.token }} trigger_phrase: "@claude" track_progress: true prompt: | @@ -238,9 +244,11 @@ jobs: Instructions: 1. Analyze the USER COMMENT to understand their intent. - 2. IF the user is explicitly asking for a review (e.g. "review this", "review my changes", "thoughts?"): + 2. IF the user is explicitly asking for a review (e.g. "review this", "review my changes", "thoughts?", or `@claude review`): - Use `signoz-docs-pr-review` for docs files (`data/docs/**`, etc). - Use `signoz-website-frontend-pr-review` for frontend files. + - Treat this as a full re-review of onboarding labeling for docs PRs. + - Follow the onboarding-label policy and summary format in `contributing/docs-review.md` via the `signoz-docs-pr-review` skill. 3. IF the user is asking for specific changes or answering a question, you may skip the full review skill and just address the request. CRITICAL: If you make ANY changes to files during this interaction, you MUST review your own changes using the relevant skill(s) before finishing. Verify they are correct, follow the style guide, and match the user's intent. diff --git a/AGENTS.md b/AGENTS.md index 8c8af75558..fe1358b845 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ Keep this file high-signal and task-oriented. Use skills for explicit, specializ If guidance conflicts, follow: 1. Direct user/developer instructions in the session -2. `CONTRIBUTING.md` +2. `CONTRIBUTING.md` and the linked playbooks under `contributing/**` 3. This file ## Agent Role @@ -41,46 +41,32 @@ You are a focused contributor for `signoz.io`. - Redirect tests: `yarn test:doc-redirects` - Metadata tests: `yarn test:docs-metadata` -## Verification Matrix +## Verification -- Docs changes (`data/docs/**`, docs images, docs nav, redirects/scripts): - - `yarn check:docs-metadata` - - `yarn check:doc-redirects` - - `yarn test:docs-metadata` - - `yarn test:doc-redirects` -- Site code changes (`app/**`, `components/**`, `hooks/**`, `utils/**`, etc.): - - `yarn lint` - - `yarn build` -- Mixed docs + code changes: run both sets. +- Use the canonical verification matrix in `contributing/repo-workflow.md#verification-matrix`. ## Task Playbooks ### Docs authoring/review (`data/docs/**`) -- Apply `CONTRIBUTING.md` directly for docs standards and checklist. -- Optimize for happy/common path first; move edge cases to troubleshooting/optional sections. -- Keep mandatory steps minimal, outcome-oriented, and in recommended defaults. -- Add links only when they help complete the current step. +- Use `CONTRIBUTING.md` as the entrypoint and `contributing/docs-authoring.md` plus `contributing/docs-review.md` for detailed standards. - If a docs path/URL changes: - add a permanent redirect in `next.config.js` - update links and `constants/docsSideNav.ts` + - update discovery surfaces when relevant (see the redirects and discovery section in `contributing/docs-authoring.md`) - For OpenTelemetry technical claims, verify against official sources first: 1. `https://opentelemetry.io/docs/*` 2. `https://github.com/open-telemetry/*` ### Blog changes (`data/blog/**`) -- Follow blog workflow sections in `CONTRIBUTING.md` ("Contribute a Doc or Blog Post" and "Blog Notes"). +- Follow `contributing/blog-workflow.md`. - Do not force docs-only checklist items when they do not apply to blogs. ### Frontend/site code (`app/**`, `components/**`, `hooks/**`, `utils/**`) -- Prefer existing patterns/components before adding abstractions. -- Use Next.js App Router conventions already present in the repo. -- Keep types/constants organized per existing conventions. +- Follow `contributing/site-code.md`. - If a change affects docs MDX components or docs rendering, verify both agent markdown (`utils/docs/agentMarkdownStubs.ts`) and Copy Markdown (`utils/docs/buildCopyMarkdownFromRendered.ts`) behavior. -- Avoid new dependencies unless required; include justification in PR context. -- Icon-card listicle data is exported through `constants/componentItems.ts`, with source data split across `constants/componentItems/*.ts` one top-level export per file. When adding or removing items from a multi-provider section (AWS / Azure / GCP, etc.), use named sub-keys (`cloud: { aws, azure, gcp }`), never a flat array split with hardcoded `slice()` indices. After editing, run `yarn tsc --noEmit` and `node --test tests/component-items-sync.test.js`. ### PR review output @@ -93,7 +79,7 @@ You are a focused contributor for `signoz.io`. ### Always - Keep changes focused and minimal for the task. -- Use explicit commands from this file and `CONTRIBUTING.md`. +- Use explicit commands from this file and the relevant `contributing/**` playbook. - Report what ran, what failed, and why. ### Ask First diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ced246ec69..3519720464 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,682 +1,52 @@ -# Contributing to SigNoz Docs and Blog +# Contributing to SigNoz Web -Thanks for helping improve SigNoz documentation. Clear, complete docs are critical for adoption of SigNoz and for the broader OpenTelemetry ecosystem. This guide explains how to contribute and the standards we follow. +Use this file as the stable entrypoint for contributing to `signoz-web`. -- Scope: The documentation content guidelines below apply to product documentation pages under `data/docs/**`. -- Development setup and local preview are in `README.md`. -- A blog contribution workflow is included later for convenience, but the content/style rules in this guide are specific to docs (not blogs). -- If your PR changes site code (for example: `app/**`, `components/**`, `hooks/**`, `utils/**`), follow [Website Code Guidelines](#website-code-guidelines). -- For questions or clarifications, open a draft PR early and ask for feedback. +- Contributors should start here, then open the task-specific playbook that matches the change. +- Reviewers and agents should use this file as the router and `contributing/**` as the detailed guidance source. +- Development setup and local preview still live in [README.md](README.md). -## Table of Contents +## Choose Your Task -- [Workflow](#workflow) -- [Git Hooks and Checks](#git-hooks-and-checks) -- [Website Code Guidelines](#website-code-guidelines) -- [General Guidelines](#general-guidelines) - - [Write docs around a Jobs-To-Be-Done (JTBD)](#write-docs-around-a-jobs-to-be-done-jtbd) -- [Documentation types and Diátaxis](#documentation-types-and-diátaxis) -- [Content Structure](#content-structure) - - [Patterns and components](#patterns-and-components) - - [Happy path vs troubleshooting](#happy-path-vs-troubleshooting) - - [URLs and redirects](#urls-and-redirects) -- [Doc Type–Specific Guidelines](#doc-type–specific-guidelines) - - [Overview docs (modules and feature families)](#overview-docs-modules-and-feature-families) - - [Product docs (features, UI flows)](#product-docs-features-ui-flows) - - [Send Data docs (instrumentation and pipelines)](#send-data-docs-instrumentation-and-pipelines) - - [Dashboard templates](#dashboard-templates) - - [Troubleshooting docs](#troubleshooting-docs) - - [User guides (end-to-end flows)](#user-guides-end-to-end-flows) - - [Explanation docs (concepts and deep dives)](#explanation-docs-concepts-and-deep-dives) - - [Reference docs (schemas, config, APIs)](#reference-docs-schemas-config-apis) - - [Sample apps (README.md files)](#sample-apps-readmemd-files) -- [Docs PR Checklist](#docs-pr-checklist) -- [Contribute a Doc or Blog Post](#contribute-a-doc-or-blog-post) +- [Write or update docs](contributing/docs-authoring.md) (includes redirects and discovery) +- [Review docs PRs](contributing/docs-review.md) +- [Change site code](contributing/site-code.md) +- [Publish or update a blog post](contributing/blog-workflow.md) +- [Follow the shared repo workflow](contributing/repo-workflow.md) +- [Use contributor templates](contributing/templates/) -## Workflow +## How To Use This Guidance -- Fork and clone the repo, then create a feature branch. -- Set up and run the site locally as per `README.md` (Node/Yarn, `yarn dev`). -- Make focused changes with meaningful commit messages. -- Build locally (`yarn build`) to catch MDX/TypeScript/Contentlayer errors. -- Open a PR as Draft by default with a clear title, context, screenshots (if relevant), and a checklist (see below). Mark it "Ready for review" when content and checks are complete. +- `contributing/**` contains the canonical task-level policy, checklists, and templates. +- `AGENTS.md`, review skills, PR templates, and workflow prompts should link to those playbooks instead of duplicating them. -## Git Hooks and Checks +## Verification -- Husky installs Git hooks automatically on `yarn install` via the `prepare` script in `package.json`. -- Pre-commit behavior - - Runs `lint-staged` on staged files. ESLint and Prettier fix typical JS/TS/MD/MDX formatting and lint issues. - - When changes include docs or redirect-related files (`data/docs/**/*.mdx`, `next.config.js`, or `scripts/check-doc-redirects.js`), it runs `yarn check:doc-redirects` to ensure renamed/moved docs have permanent redirects. - - When changes include docs (`data/docs/**/*.mdx`), it runs `yarn check:docs-metadata` to ensure metadata such as date, description, tag, title is complete and correct. -- Fixing failures - - Lint/format: run `yarn lint` or re-stage after auto-fixes from Prettier/ESLint. - - Redirects: run `yarn check:doc-redirects` locally to see missing entries, then add a permanent redirect in `next.config.js` under `async redirects()`. Re-stage and commit. - - Metadata: run `yarn check:docs-metadata` locally to see missing/invalid entries, then update the metadata in the `.mdx` file. Re-stage and commit. - - Optional: `yarn test:doc-redirects` runs a small test for redirect rules. -- Hooks path - - The repo uses Husky v9 defaults (`core.hooksPath=.husky`). If your local Git still points elsewhere (e.g., `.husky/_` from older setups), run `git config core.hooksPath .husky` or re-run `yarn install` to refresh hooks. -- Bypass (rare) - - In emergencies you can use `git commit --no-verify`, but please fix issues instead of bypassing checks in normal workflows. +Use the canonical verification matrix in [contributing/repo-workflow.md](contributing/repo-workflow.md#verification-matrix). -### CI checks (GitHub Actions) +## Shared PR Workflow -- Docs Redirect Guard - - Triggers on PRs that touch `data/docs/**`, `next.config.js`, `scripts/check-doc-redirects.js`, tests, or `package.json`. - - Runs `yarn test:doc-redirects` and `yarn check:doc-redirects`. - - Fails if redirects are missing/invalid or tests fail. Fix by adding permanent redirects in `next.config.js` and re-running locally. -- Docs Metadata Guard - - Triggers on PRs that touch `data/docs/**`, `next.config.js`, `scripts/check-docs-metadata.js`, tests, or `package.json`. - - Runs `yarn test:docs-metadata` and `yarn check:docs-metadata`. - - Fails if title, date, description are missing/invalid, and warns if tags are missing from MDX files. Fix by adding relevant metadata in MDX file and re-running locally. -- Add to Onboarding (label-driven) - - When a PR is labeled `add-to-onboarding`, this job checks that the PR includes docs changes. If none are found, the job fails with a message. - - If docs are present, it auto-creates an onboarding issue listing changed docs and comments on the PR with a link. +1. Fork and clone the repo. +2. Create a focused branch. +3. Make task-scoped changes. +4. Run the checks that match your files using the matrix in [contributing/repo-workflow.md](contributing/repo-workflow.md#verification-matrix). +5. Open the PR as Draft by default. +6. Mark it ready only after checks and self-review are complete. -## Website Code Guidelines +See [contributing/repo-workflow.md](contributing/repo-workflow.md) for Git hooks, CI checks, and failure handling. -These guidelines apply when your PR changes website code (for example: `app/**`, `components/**`, `hooks/**`, `utils/**`). +## Quick Rules -- Prefer existing icon libraries - - Use `lucide-react` or `react-icons` for icons. - - If you need a custom brand/logo asset, place it under `public/svgs/**` and reference it via `/svgs/...` (avoid inline SVG blobs in components). -- Prefer existing UI primitives - - Use existing components in `components/ui/**` (for example `components/ui/Button`) instead of raw HTML elements for interactive UI. - - Avoid styling overrides unless necessary; keep Tailwind classes consistent with existing patterns. -- Keep types/constants co-located and reusable - - Move component-local types/constants into separate files (for example `MyComponent.types.ts`, `MyComponent.constants.ts`) and export from the folder `index.ts` when needed outside the folder. -- Add listicle items to `constants/componentItems.ts`, not inside component files - - `constants/componentItems.ts` is the public entrypoint for icon-card grid data (APM, Logs, Dashboards, and so on). Source data lives in `constants/componentItems/*.ts`, with one top-level export per file, and both the UI components and the agent markdown stubs import through the barrel. - - Flat list (`ComponentItem[]`): use when all items belong to one logical group with no sub-sections. - - Sectioned object (`{ sectionKey: ComponentItem[] }`): use when items are rendered in labelled sub-sections (for example `aws`, `azure`, `gcp`). Pair it with a `getAll*()` helper that spreads every sub-array. **Never split a flat array with hardcoded `slice()` indices** — use named sub-keys instead so adding or removing an item in one section cannot silently shift another. - - After adding items, add a matching entry in the component's `ICON_MAP` (keyed by `href`) and run `yarn tsc --noEmit` to verify. -- Avoid concurrent async invocations - - For click handlers that do async work, prevent multiple concurrent runs (set loading state before `await` and/or guard with a ref). -- Be deliberate about DOM cleanup/transforms - - When cleaning up rendered DOM before transforming (for example, HTML → Markdown), avoid redundant selectors and ensure cleanup order matches the intended behavior. -- Keep docs MDX components compatible with agent-markdown output - - If you add or change an MDX component used under `data/docs/**`, review its agent rendering in `utils/docs/agentMarkdownStubs.ts`. - - Add or update tests in `tests/agent-markdown-*.test.js`. The docs-wide component coverage test should stay green so new components are explicitly reviewed. - - If the component affects rendered article markup, also verify the `Copy Markdown` flow still produces clean output via `utils/docs/buildCopyMarkdownFromRendered.ts` and add/update targeted tests when practical. -- Dependencies must be justified - - Do not add new packages unless they are required and there is no existing dependency that fits. - - If you add a dependency, include a short justification in the PR description and ensure it is used in code. +- Keep changes minimal and scoped to the task. +- Use existing patterns before creating new abstractions. +- Do not bypass failing checks silently. +- If a docs URL changes, also handle redirects, sidebar updates, and any discovery surfaces. +- For OpenTelemetry technical claims, verify against official OpenTelemetry docs or repositories. -## General Guidelines +## Need More Detail? -- Assume language/framework basics, but assume no prior OpenTelemetry knowledge. - - Do not explain programming fundamentals. - - Briefly explain OTel terms on first use and link to references. -- Write concise, task-first instructions. - - Avoid filler, hype, and generic intros. - - Use active voice and second person. -- Keep terminology and naming consistent across pages. -- Be explicit about caveats and limitations (version, environment, scale, beta gaps). -- Prefer concrete examples over abstract descriptions. -- Define acronyms on first use, then use the short form consistently. -- Use angle-bracket placeholders only (``, ``) and explain each placeholder right below the snippet. -- Cross-link existing SigNoz docs instead of duplicating instructions. -- AI/LLM use is fine for research, but all output must be verified and rewritten clearly. - -### Write docs around a Jobs-To-Be-Done (JTBD) - -- Identify persona(s), assumptions, and the primary job before drafting. -- Keep persona as an authoring aid; do not add a mandatory "Target Persona" section in docs. -- Define the primary job in one sentence: "When ..., I want to ..., so I can ...". -- Optimize for time-to-first-success: - - one clear default path - - minimal mandatory steps - - clear success signal in SigNoz -- Keep the happy/common path clean. - - Move optional, advanced, and edge-case content to callouts, collapsed sections, troubleshooting, or separate pages. -- For setup docs, scope the main flow to prerequisites, install/configure, start/restart, and validate. - -## Documentation types and Diátaxis - -Classify each doc by its primary purpose using [Diátaxis](https://diataxis.fr/) and set `doc_type` in frontmatter: - -- `tutorial`: learn by doing (opinionated end-to-end flow) -- `howto`: complete a specific task -- `reference`: look up exact facts (options, schemas, limits) -- `explanation`: understand how/why something works - -Rough mapping: - -- Send Data docs: usually `howto` -- User guides (end-to-end flows): usually `tutorial` -- Conceptual knowledge base: `explanation` -- Schemas/options/limits: `reference` -- Troubleshooting docs: `howto` with problem-first framing - -## Content Structure - -Every docs page should be skimmable, actionable, and validated. - -- Required frontmatter: - ```yaml - --- - date: 2025-01-15 # YYYY-MM-DD - id: - title: - description: <1-2 line summary with key terms> - doc_type: howto # tutorial | howto | reference | explanation - # tags optional; see rules below - --- - ``` -- Tags: - - omit `tags` when doc applies to both Cloud and Self-Host - - `tags: [Self-Host]` for self-host-only docs - - `tags: [SigNoz Cloud]` for cloud-only docs - - `tags: []` if none apply -- Standard sections (H2): - - `## Overview` (skip if intro is already 1-2 lines) - - `## Prerequisites` - - `## Steps` (or clear setup sections) - - `## Validate` - - `## Troubleshooting` - - `## Limitations` (when relevant) - -- Commands and snippets: - - Explain what each command does and where to run it. - - State expected result after major steps. - - Annotate code blocks with language and filename when useful. - - Explain important fields and placeholders directly below snippets. - - Highlight specific lines to focus attention using braces after the language identifier. Example: highlight line 4 in a YAML block: - - ````markdown - ```yaml {4} - service: - .... - logs: - receivers: [otlp, syslog] - processors: [batch] - exporters: [otlp] - ``` - ```` - - This renders as: - ![Highlighted line example](public/img/docs/guidelines/code-highlight-example.png) - - Immediately below, explain each critical field and placeholder. - - Example with placeholders and explanations: - ```yaml:/deploy/docker/otel-collector-config.yaml - exporters: - otlphttp: - endpoint: https://ingest.<region>.signoz.cloud:443 - headers: - signoz-ingestion-key: <your-ingestion-key> - service: - pipelines: - traces: - exporters: [otlphttp] - ``` - This configures the OTel Collector to export traces to SigNoz Cloud using the OTLP/HTTP protocol. Read more about OTel Collector configuration [here](https://signoz.io/docs/collection-agents/opentelemetry-collector/configuration/). - - Verify these values: - - `<region>`: Your SigNoz Cloud [region](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint) - - `<your-ingestion-key>`: Your SigNoz [ingestion key](https://signoz.io/docs/ingestion/signoz-cloud/keys/) - - **Append, don't replace**: When showing OpenTelemetry Collector configuration (e.g., adding a new receiver or exporter), show only the specific snippet to add and instruct the user to **append** it to their existing `otel-collector-config.yaml` and **enable** it in the pipeline. Avoid showing a full `otel-collector-config.yaml` that users might copy-paste, overwriting their existing setup (like resource detectors or other processors). - - ✅ "Add the `filelog` receiver to your `receivers` section and enable it in `service.pipelines.logs`." - - ❌ "Replace your `otel-collector-config.yaml` with the following content:" - - Main-path snippets must be safe defaults that work after replacing documented placeholders. - - Move advanced/environment-specific options into callouts or collapsed sections. - -- Hyperlinks: - - Internal links should use absolute URLs. Use `[Text](https://signoz.io/endpoint)` rather than site-relative `[Text](/endpoint)`. - - Add links where they directly help users finish the current step. - - Avoid link dumping. - - External links in MDX should use: - ```mdx - <a href="https://example.com" target="_blank" rel="noopener noreferrer nofollow"> - Example - </a> - ``` - - Use descriptive anchor text (avoid "here" and raw URLs in body text). - - Validate all internal and external links before PR. - -- Cloud vs Self-Host: - - Default to SigNoz Cloud examples. - - Use a collapsible `KeyPointCallout` for self-hosted users instead of duplicating with tabs. - - Use the Cloud vs Self-Hosted comparison doc when a guide only shows one environment and the other only differs by endpoint/auth/TLS: https://signoz.io/docs/ingestion/cloud-vs-self-hosted/#self-hosted-to-cloud - - Use tabs only when the workflows materially differ. -- Images and SEO: - - Store docs images in `public/img/docs/<topic>/...`, reference `/img/docs/<topic>/...`. - - Use `Figure` with descriptive alt text and concise caption. - - Use WebP format for all images. See [Creating WebP images doc](https://signoz.notion.site/Creating-webp-images-7c27a266c4ae4ea49a76a2d3ba3296a5?pvs=74) for tips and tools - - Include primary keywords in title, description, slug, and first paragraph. - - Use natural variants/synonyms in headings and body. - -### Patterns and components - -- Use `Admonition` for notes, warnings, and tips: - ```mdx - <Admonition type="info">Short, actionable note.</Admonition> - ``` -- Use `KeyPointCallout` for collapsible supplementary info: - ```mdx - <KeyPointCallout title="Optional details" defaultCollapsed={true}> - Content that users can expand if needed. - </KeyPointCallout> - ``` -- Use `Tabs`/`TabItem` to branch by platform, OS, or materially different flows. For Cloud vs Self-Host, prefer the drop-in snippet + comparison page. -- Use numbered steps for procedures and bullets for reference content. -- In procedure docs, each numbered step should include: what to do, the exact command/config change, and the expected result. -- Keep mandatory steps to the minimum needed for first success. -- Merge or remove redundant mandatory steps. -- Optional or advanced variations should not appear in the primary numbered flow. -- Each required step must be unambiguous, actionable, and outcome-oriented. -- Avoid multi-purpose steps that combine unrelated actions. -- Convert non-essential, edge-case, or optional steps into `KeyPointCallout` or collapsed `<details>` blocks to keep the main flow focused. -- Keep headings short and meaningful. Prefer H2 for main sections. - -### Happy path vs troubleshooting - -- Write for the happy/common path first. -- Keep mandatory steps minimal and focused on first success. -- Keep the main path free of tangential details. -- Put common blockers as short inline warnings near the step. -- Put rare/verbose debugging in `## Troubleshooting` or a dedicated troubleshooting doc. -- If users need guesswork to continue, rewrite the step or add one high-value link. - -### URLs and redirects - -- URL derives from file path and name: - - Docs: `data/docs/<section>/<slug>.mdx` renders at `/docs/<section>/<slug>/`. - - Blog: `data/blog/<slug>.mdx` renders at `/blog/<slug>/`. -- Avoid changing URLs of live content. If you must rename or move a page, add a permanent redirect from the old path to the new path so existing links don’t break and SEO is preserved. -- Add redirects in `next.config.js` under `async redirects()` using `permanent: true`: - - ```js - // next.config.js - async redirects() { - return [ - { - source: '/docs/instrumentation/opentelemetry-cloudflare/', - destination: '/docs/instrumentation/cloudflare-workers/', - permanent: true, // permanent redirect (search engines treat like 301/308) - }, - ] - } - ``` - -- Keep trailing slashes consistent (this repo sets `trailingSlash: true`). -- Update internal links and the sidebar entry in `constants/docsSideNav.ts` when a doc path changes. - -## Doc Type–Specific Guidelines - -### Overview docs (modules and feature families) - -- Audience: readers deciding where to start. -- Include what the module does, when to use it, and where to go next. -- Link to setup/how-to/tutorial/reference pages by intent. -- Avoid step-by-step setup and long config/reference tables. -- `doc_type` is usually `explanation`. - -### Product docs (features, UI flows) - -- Start from the user job and expected outcome. -- Include exact UI path/labels, prerequisites, step-by-step flow, and validation. -- Keep deep concepts in separate explanation docs; link them. -- `doc_type` is usually `howto` (or `explanation` if concept-only). - -### Send Data docs (instrumentation and pipelines) - -- Primary job: get telemetry flowing quickly. -- Always include a concrete `## Validate` section. - -#### Audience assumptions - -- Readers know their language/framework basics. -- Readers may not know OTel concepts or pipeline patterns. -- Explain OTel terms briefly; do not teach language fundamentals. - -#### URL and naming - -- Explicitly mention OpenTelemetry in the URL/slug, title, and overview. - - Example slug and file name: `data/docs/instrumentation/<tech>/opentelemetry-<tech>.mdx`. -- Specify tested versions when relevant. -- Use pinned/tested/latest versions in main steps; keep version caveats in optional notes. - -#### Default to direct export to SigNoz Cloud - -- Use direct export to SigNoz Cloud as the primary path. -- Keep Collector-based setup optional and out of the main path. Include it as a collapsible section at the end. - -#### Deployment types - -- Cover VM, Kubernetes, Docker, and Windows when applicable. -- If flows differ by platform, use tabs. -- Include a VM explanation callout at the start of the VM section: - -```mdx -<KeyPointCallout title="What classifies as VM?" defaultCollapsed={true}> -A VM is a virtual computer that runs on physical hardware. This includes: -- **Cloud VMs**: AWS EC2, Google Compute Engine, Azure VMs, DigitalOcean Droplets -- **On-premise VMs**: VMware, VirtualBox, Hyper-V, KVM -- **Bare metal servers**: Physical servers running Linux/Unix directly - -Use this section if you're deploying your application directly on a server or VM without containerization. -</KeyPointCallout> -``` - -#### Self-hosted callout - -Include this callout near the top of each Send Data doc: - -```mdx -<KeyPointCallout title="Using self-hosted SigNoz?" defaultCollapsed={true}> -Most steps are identical. To adapt this guide, update the endpoint and remove the ingestion key header as shown in [Cloud → Self-Hosted](https://signoz.io/docs/ingestion/cloud-vs-self-hosted/#cloud-to-self-hosted). -</KeyPointCallout> -``` - -#### Optional Collector setup section - -If Collector is optional, keep it in a collapsed section near the bottom. Eg: -```mdx -<details> -<ToggleHeading> -## Setup OpenTelemetry Collector (Optional) -</ToggleHeading> - -### What is the OpenTelemetry Collector? - -Think of the OTel Collector as a middleman between your app and SigNoz. Instead of your application sending data directly to SigNoz, it sends everything to the Collector first, which then forwards it along. - -### Why use it? - -- **Cleaning up data** — Filter out noisy traces you don't care about, or remove sensitive info before it leaves your servers. -- **Keeping your app lightweight** — Let the Collector handle batching, retries, and compression instead of your application code. -- **Adding context automatically** — The Collector can tag your data with useful info like which Kubernetes pod or cloud region it came from. -- **Future flexibility** — Want to send data to multiple backends later? The Collector makes that easy without changing your app. - -See [Switch from direct export to Collector](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/switch-to-collector/) for step-by-step instructions to convert your setup. - -For more details, see [Why use the OpenTelemetry Collector?](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/why-to-use-collector/) and the [Collector configuration guide](https://signoz.io/docs/opentelemetry-collection-agents/opentelemetry-collector/configuration/). - -</details> -``` - -#### Code and configuration - -- Explain what each snippet does, where it goes, and why it is needed. -- Keep default config minimal for first success. -- Move non-essential options (`debug`, self-scrape, extra detectors, placeholder paths) out of the main flow. - -#### Troubleshooting section - -- Include `## Troubleshooting` with symptoms, likely causes, concrete fixes, and verification. -- Include frequent checks: endpoint, auth key/token, TLS, versions. -- Use error-string or problem-style headings for discoverability. -- For Send Data docs, use collapsed troubleshooting sections with `<ToggleHeading>`. -- Don’t stop at “Data Sent”. Close the loop with next steps: Link to relevant dashboards or dashboard templates, example alerts, service and trace views, and deeper user guides so the doc completes an end-to-end workflow. -- `doc_type` is usually `howto` for Send Data docs. - -### Dashboard templates - -- Always include a short prerequisite or info note near the top that links to setting up the data source and sending telemetry to SigNoz. - - Link the relevant instrumentation/observability guide for the technology (for example, Mastra → https://signoz.io/docs/mastra-observability/). -- Include a **Dashboard Preview** (screenshot) near the top. Use the `Figure` component with descriptive `alt` and a concise `caption`. -- Provide **import instructions** using the `DashboardActions` helper (include both dashboard JSON link and import steps). -- Include a **What This Dashboard Monitors** section that describes the key metrics and insights this dashboard provides. -- Include a **Metrics Included** section that lists the metrics included in the dashboard. -- Cross-link adjacent dashboards and related user guides in the **Next Steps** section. -- `doc_type` is usually `explanation` for Dashboard Template docs. - -### Troubleshooting docs - -- Start with the problem statement and affected environments. -- Structure: Symptoms -> Likely causes -> Resolution -> Verification. -- Include concrete logs/commands and known edge cases. -- Titles and headings: use question-style titles or include the exact error/topic to improve search and SEO. Prefer exact error strings and component names (SDK/receiver/exporter) in headings. -- For minor, frequently asked Q&A, add/update a concise FAQ page. Keep answers short and point to deeper guides when needed. -`doc_type` for troubleshooting docs is `howto`. Treat each page as a focused “how to fix this specific problem” guide, with a problem-first title and concrete resolution steps. - -### User guides (end-to-end flows) - -- Goal-oriented, step-by-step flows that combine multiple features or modules. -- Assume minimal context, but link to existing setup/instrumentation where needed. -- Include “Expected result” at the end of each major step. -- End with “Next steps” and links to deeper topics or automation. -- `doc_type` is usually `tutorial` for these end-to-end guides. Use `howto` for narrower, single-task pages. - -### Explanation docs (concepts and deep dives) - -Explanation docs are where we answer **“why does this work like this?”** and **“how does this fit together?”** - -- The job is "build a mental model." - -- Audience: users trying to build a mental model or make design decisions. -- Cover: - - Core observability concepts in SigNoz (for example, how traces become APM metrics, how logs are stored and queried, how sampling or retention works). - - Trade-offs and design choices (for example, cardinality, aggregation strategies, performance considerations). - - Conceptual breakdowns of complex features (for example, query builder queries, metric types, etc.). -- Structure: - - Use diagrams, examples, and scenarios to explain ideas. - - Link out to how-to guides for concrete steps and to reference docs for raw details. -- Avoid: - - Step-by-step task flows. - - Large tables of options or fields (those belong in reference). - -Set `doc_type: explanation` for these pages. - -### Reference docs (schemas, config, APIs) - -Reference docs exist so users can **look up exact facts** quickly. - -- The job is "look up exact facts." Lead with the answer; keep prose minimal. - -- Audience: users who already know *what* they’re doing and just need details. -- Cover: - - Configuration options, environment variables, CLI flags. - - Ingestion endpoints, ports, authentication headers. - - Metrics, logs, and traces schemas (field names, types, units, example values). - - Limits, quotas, and version/plan availability. -- Structure: - - Use tables, lists, and short descriptions. - - Link back from how-to and tutorial docs instead of duplicating. - - Keep examples minimal and purely illustrative (no deep narratives). -- Avoid: - - Guided workflows (“first do X, then Y…”). - - Long conceptual intros — keep context tight and link to explanation docs instead. -- Use `doc_type: reference`. - -### Sample apps (README.md files) - -- Generally present as individual repo under the [SigNoz GitHub organization](https://github.com/SigNoz). -- Use the correct endpoints and link ingestion docs: - - Cloud: `https://ingest.<region>.signoz.cloud:443` with `signoz-ingestion-key`. Also link to the Cloud ingestion references: [endpoint guide](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint) and [keys](https://signoz.io/docs/ingestion/signoz-cloud/keys/) - - Self-Host: `http://<otel-collector-host>:4318` or `:4317` (OTLP/HTTP vs OTLP/gRPC). Also link to the Cloud → Self-Hosted adaptation guidance: [cloud to self-hosted](https://signoz.io/docs/ingestion/cloud-vs-self-hosted/#cloud-to-self-hosted) -- Document how to configure and run locally and in Docker/Kubernetes. -- Include a `README.md` with a link to the relevant docs page. -- Keep versions and instructions in sync across docs, sample apps, and blogs. -- Provide a “Validate in SigNoz” section that shows where the data will appear. - -## Docs PR Checklist - -- [ ] Frontmatter includes `date`, `id`, `title`, `description`, `doc_type`, and correct tags. -- [ ] SEO: primary keywords appear in `title`, `description`, URL/slug, and the first paragraph. For Send Data docs, include "OpenTelemetry" in slug/title. -- [ ] Content matches the chosen `doc_type`. -- [ ] Primary persona and primary job are clear in scope and flow. -- [ ] Happy/common path is easy to follow end-to-end. -- [ ] Steps are clear, concise, and minimal for first success. -- [ ] Recommended/default config is in main flow; advanced options are moved to optional/collapsed sections. -- [ ] `## Validate` clearly shows where success appears in SigNoz. -- [ ] `## Troubleshooting` includes symptom -> cause -> fix -> verification. -- [ ] Commands/snippets explain what, where, and expected outcome. -- [ ] Placeholders use `<...>` format and are documented. -- [ ] Default snippets are runnable after placeholder replacement. -- [ ] Relevant internal/external links are included where helpful (without link dumping). -- [ ] Internal links use `https://signoz.io/...`; no preview/staging domains. -- [ ] All links were manually validated as live. -- [ ] Images (if any) use WebP, clear alt/caption, and correct path under `public/img/docs/...`. -- [ ] Sidebar entry is added/updated in `constants/docsSideNav.ts` when needed. -- [ ] If URL changed: permanent redirect added in `next.config.js` and redirect checks were run. -- [ ] For Send Data docs: cloud-first default path, self-hosted callout, and optional Collector section near bottom. -- [ ] For Send Data docs: include VM/Kubernetes/Docker/Windows paths where applicable. -- [ ] Built locally (`yarn build`) and reviewed at `http://localhost:3000`. - -## Contribute a Doc or Blog Post - -Follow the steps below to create and submit either a blog post or a documentation page. Where the flow differs, look for the Blog vs Docs notes. - -### Step 1: Fork the Repository - -1. Go to the [signoz.io GitHub repository](https://github.com/SigNoz/signoz.io). -2. Click on the "Fork" button at the top-right corner of the page. This will create a copy of the repository under your GitHub account. - -### Step 2: Clone Your Forked Repository - -1. On your GitHub account, navigate to the forked repository. -2. Click the "Code" button and copy the URL. -3. Open your terminal and run the following command to clone the repository: - - ```bash - git clone https://github.com/<your-username>/signoz.io.git - ``` - -4. Navigate into the cloned directory: - - ```bash - cd signoz.io - ``` - -### Step 3: Set Up the Upstream Repository - -Setting up the upstream repository allows you to fetch changes from the original repository and keep your fork in sync. - -1. Add the original repository as the upstream remote: - - ```bash - git remote add upstream https://github.com/SigNoz/signoz.io.git - ``` - -2. Verify the new remote named `upstream`: - - ```bash - git remote -v - ``` - -### Step 4: Create a New Branch - -Create a new branch for your changes to keep work isolated and reviewable. - -```bash -git checkout -b add-new-content -``` - -### Step 5: Create Your Content (Blog or Docs) - -- Blog - - 1. Navigate to `data/blog`: - ```bash - cd data/blog - ``` - 2. Create a new `.mdx` file. The file name should match the post slug. Example for `https://signoz.io/blog/opentelemetry-spring-boot/`: - `opentelemetry-spring-boot.mdx`. - 3. Write your post. Use existing posts in `data/blog` as reference and include: - - Cover image - - Frontmatter metadata: `title`, `date`, `author`, `tags`, `canonicalUrl` (if applicable) - - Internal links as absolute URLs (see link policy above) - -- Docs - 1. Navigate to `data/docs` (choose the right section folder) and create a new `.mdx` file. Example: - `data/docs/instrumentation/opentelemetry-cloudflare.mdx`. - 2. Add required frontmatter and structure. At minimum include: - ```yaml - --- - date: 2025-01-15 - id: <unique-id-or-slug> - title: <Title in Sentence Case> - description: <1–2 line summary> - # tags are optional — see Content Structure section above - --- - ``` - Then follow the “Content Structure” guidelines in this document for sections like Overview, Prerequisites, Steps, Validate, and Troubleshooting. - -### Step 6: Add Images - -- Blog images - - - Place under `public/img/blog/<YYYY-MM>/` (create the monthly folder if needed). - - Use WebP format (`.webp`) whenever possible. Conversion tips: https://signoz.notion.site/Creating-webp-images-7c27a266c4ae4ea49a76a2d3ba3296a5?pvs=74 - -- Docs images - - Place under `public/img/docs/` and, when possible, follow the existing folder organization for the topic/feature. - - Use WebP format (`.webp`) whenever possible. Conversion tips: https://signoz.notion.site/Creating-webp-images-7c27a266c4ae4ea49a76a2d3ba3296a5?pvs=74 - -### Step 7: Add Doc to Sidebar (Docs only) - -Docs pages must be added to the sidebar navigation. - -1. Open `constants/docsSideNav.ts`. -2. Add a new entry under the appropriate category with a route that matches your page path and a human‑readable label. Example: - - ```ts - { - type: 'doc', - route: '/docs/instrumentation/opentelemetry-cloudflare', - label: 'Cloudflare', - } - ``` - -If you introduced a new tag in your doc frontmatter, add its tooltip definition in `constants/tagDefinitions.ts`. - -If your new doc adds a new surfaced integration, data source, installation path, dashboard template, or similar item that appears in docs listicles/overview cards, also update the relevant component data under `constants/componentItems/*.ts` while keeping `constants/componentItems.ts` as the public entrypoint, and update the matching component `ICON_MAP` where needed. This is similar to the sidebar rule: if the doc should be discoverable from an existing docs surface, update that surface in the same PR. - -### Step 8: Add and Commit Your Changes - -```bash -git add . -git commit -m "Add new blog/doc: <title>" -``` - -### Step 9: Fetch and Merge Upstream Changes - -Keep your branch current before pushing: - -```bash -git fetch upstream -git merge upstream/main -``` - -### Step 10: Push Your Changes - -```bash -git push origin add-new-content -``` - -### Step 11: Test Your Changes Locally - -After setting up your environment (see README’s Development Setup), verify the site: - -```bash -yarn install -yarn build -yarn dev -``` - -Open `http://localhost:3000` and review your blog/doc page. - -### Step 12: Create a Pull Request - -1. Navigate to your fork on GitHub. -2. Click "Compare & pull request". -3. Add a succinct title and description. -4. Submit the PR as a Draft (default). -5. When the page builds cleanly and vercel preview is ready, click "Ready for review". - -### Blog Notes - -- Refer to existing blogs in `data/blog` for structure. -- Include a relevant cover image and complete metadata for SEO. -- Place blog images under `public/img/blog/<YYYY-MM>/`. - -### Docs Notes - -- Follow the “Content Structure” and “Doc Type–Specific Guidelines” above. -- Images go under `public/img/docs/`. -- Add the page to `constants/docsSideNav.ts` so it appears in the left sidebar. -- If the doc should appear in a docs listicle, quick-start overview, or similar card-based discovery surface, add/update the matching item in the relevant `constants/componentItems/*.ts` module and keep it exported through `constants/componentItems.ts`. Update the component's `ICON_MAP` when needed. -- If you add new tags, define tooltips in `constants/tagDefinitions.ts`. -- If you change a live doc’s URL (rename or move), add a permanent (301/308) redirect in `next.config.js` `redirects()` from the old path to the new one and update any internal links. - -Thanks again for contributing to SigNoz! +- Docs structure, JTBD guidance, snippets, redirects, and Send Data rules: [contributing/docs-authoring.md](contributing/docs-authoring.md) +- Docs review rubric and onboarding label policy: [contributing/docs-review.md](contributing/docs-review.md) +- Frontend conventions and MDX rendering constraints: [contributing/site-code.md](contributing/site-code.md) +- Blog-specific workflow: [contributing/blog-workflow.md](contributing/blog-workflow.md) +- Reusable templates and checklist snippets: [contributing/templates/](contributing/templates/) diff --git a/README.md b/README.md index 4057a99952..f55ee677cc 100644 --- a/README.md +++ b/README.md @@ -51,11 +51,11 @@ ### Git Hooks -- We use Husky for pre-commit checks. See details in [CONTRIBUTING.md#git-hooks-and-checks](CONTRIBUTING.md#git-hooks-and-checks). +- We use Husky for pre-commit checks. See [contributing/repo-workflow.md#git-hooks-and-checks](contributing/repo-workflow.md#git-hooks-and-checks). # Contributing -Looking to contribute a blog or improve docs? See the full guidelines in [CONTRIBUTING.md](CONTRIBUTING.md), including blog contribution steps, docs standards, and the PR checklist. +Looking to contribute a blog, docs page, or site change? Start with [CONTRIBUTING.md](CONTRIBUTING.md), then use the task-specific playbooks under [contributing/](contributing/). If you have any questions or need further assistance, feel free to reach out to us on [SigNoz Slack Community](https://signoz.io/slack). diff --git a/contributing/blog-workflow.md b/contributing/blog-workflow.md new file mode 100644 index 0000000000..c9e0d42d47 --- /dev/null +++ b/contributing/blog-workflow.md @@ -0,0 +1,36 @@ +# Blog Workflow + +Use this playbook for content under `data/blog/**`. + +## Blog Expectations + +- Follow the shared repo workflow in [repo-workflow.md](repo-workflow.md). +- Do not force docs-only structure or checklist items onto blog posts. +- Use existing posts in `data/blog/**` as local style references when formatting a new post. + +## Blog Metadata + +At minimum, include: + +- `title` +- `date` +- `author` +- `tags` +- `canonicalUrl` when applicable + +## Images + +- Store blog images under `public/img/blog/<YYYY-MM>/`. +- Use WebP when possible. + +## Authoring Notes + +- Use absolute production URLs for internal links. +- Keep the title, description, and metadata aligned with the post topic. +- If the blog references product setup or instrumentation, link to the relevant docs instead of reproducing long setup instructions in full. + +## Submission + +- Run the shared checks from [repo-workflow.md](repo-workflow.md) that apply to your change. +- Open the PR as Draft by default. +- Include screenshots when the post depends on visual context. diff --git a/contributing/docs-authoring.md b/contributing/docs-authoring.md new file mode 100644 index 0000000000..5f808f0321 --- /dev/null +++ b/contributing/docs-authoring.md @@ -0,0 +1,284 @@ +# Docs Authoring + +Use this playbook for product documentation under `data/docs/**`. + +## Core Writing Principles + +- Assume readers know their language or framework basics, but may not know OpenTelemetry concepts. +- Write concise, task-first instructions in active voice. +- Keep terminology consistent across pages. +- Be explicit about caveats such as versions, environments, or beta gaps. +- Prefer concrete examples over abstract descriptions. +- Define acronyms on first use, then use the short form consistently. +- Use angle-bracket placeholders only, such as `<region>` or `<your-ingestion-key>`, and explain them right below the snippet. +- Cross-link existing SigNoz docs instead of duplicating instructions. +- AI-assisted drafting is fine, but every claim must be verified and rewritten clearly. + +## JTBD-First Authoring + +- Identify the primary persona and primary job before drafting. +- Use persona as an authoring aid, not as a required section in the doc. +- Define the primary job in one sentence: "When ..., I want to ..., so I can ...". +- Optimize for time-to-first-success: + - one clear default path + - minimal mandatory steps + - a clear success signal in SigNoz +- Keep the happy path clean. +- Move optional, advanced, or edge-case material into callouts, collapsible sections, troubleshooting, or separate pages. +- For setup docs, keep the main flow scoped to prerequisites, install or configure, start or restart, and validate. + +## Diataxis And `doc_type` + +Set `doc_type` by primary purpose: + +- `tutorial`: learn by doing with an opinionated end-to-end flow +- `howto`: complete a specific task +- `reference`: look up exact facts, options, schemas, or limits +- `explanation`: build a mental model or understand trade-offs + +Common mapping: + +- Send Data docs: usually `howto` +- User guides: usually `tutorial` +- Conceptual docs: `explanation` +- Schemas and limits: `reference` +- Troubleshooting docs: `howto` with problem-first framing + +## Required Frontmatter + +Use the template in [templates/docs-frontmatter.md](templates/docs-frontmatter.md). + +Required keys: + +- `date` +- `id` +- `title` +- `description` +- `doc_type` + +Tags: + +- omit `tags` when the doc applies to both Cloud and Self-Host +- use `tags: [Self-Host]` for self-host-only docs +- use `tags: [SigNoz Cloud]` for cloud-only docs +- use `tags: []` only when none apply + +## Standard Page Structure + +Use the template in [templates/docs-page.md](templates/docs-page.md). + +Prefer these H2 sections when they fit the doc: + +- `## Overview` +- `## Prerequisites` +- `## Steps` or clear setup sections +- `## Validate` +- `## Troubleshooting` +- `## Limitations` + +## Commands, Snippets, And Examples + +- Explain what each command does and where to run it. +- State the expected result after major steps. +- Annotate code blocks with language and filename when useful. +- Explain important fields and placeholders directly below snippets. +- Main-path snippets should be safe defaults that work after placeholder replacement. +- Move advanced or environment-specific options into callouts or collapsed sections. + +### Collector Config Safety + +When documenting OpenTelemetry Collector changes: + +- show only the snippet to add +- tell readers to append it to their existing `otel-collector-config.yaml` +- tell readers where to enable it in the relevant pipeline +- do not tell readers to replace the entire collector config unless the page is explicitly about a full clean-room setup + +## Links And Media + +- Internal links should use absolute production URLs such as `https://signoz.io/docs/...`. +- Add links where they directly help readers complete the current step. +- Avoid link dumping. +- External links in MDX should use: + +```mdx +<a href="https://example.com" target="_blank" rel="noopener noreferrer nofollow"> + Example +</a> +``` + +- Use descriptive anchor text instead of "here" or raw URLs in body text. +- Validate all added internal and external links before the PR. +- Store docs images under `public/img/docs/<topic>/...`. +- Use WebP when possible. +- Use `Figure` with descriptive alt text and a concise caption. + +## Patterns And Components + +- Use `Admonition` for notes, warnings, and tips. +- Use `KeyPointCallout` for supplementary or optional material. +- Use `Tabs` and `TabItem` only when flows materially differ by platform or environment. +- Prefer numbered steps for procedures and bullets for reference content. +- Keep headings short and meaningful. + +## Happy Path Vs Troubleshooting + +- Write for the happy or common path first. +- Keep mandatory steps minimal and focused on first success. +- Put common blockers as short warnings near the relevant step. +- Put rare or verbose debugging into `## Troubleshooting` or a dedicated troubleshooting page. +- If users would need guesswork to continue, rewrite the step or add one high-value link. + +## Send Data Docs + +Use the template in [templates/send-data-doc.md](templates/send-data-doc.md). + +- Primary job: get telemetry flowing quickly. +- Always include a concrete `## Validate` section. +- Mention OpenTelemetry in the URL, slug, title, and overview. +- Use direct export to SigNoz Cloud as the primary path. +- Keep Collector-based setup optional and near the bottom. +- Include the self-hosted adaptation callout near the top. +- Cover VM, Kubernetes, Docker, and Windows when those paths materially apply. +- For Send Data docs, use collapsed troubleshooting sections with `ToggleHeading`. +- Close the loop with next steps such as dashboards, alerts, traces, or deeper guides. + +## Doc-Type Guidance + +### Overview Docs + +- Help readers decide where to start. +- Explain what the module does, when to use it, and where to go next. +- Avoid long step-by-step setup or large reference tables. + +### Product Docs + +- Start from the user job and expected outcome. +- Include exact UI paths, prerequisites, steps, and validation. +- Move deep concepts to separate explanation docs. + +### Dashboard Templates + +- Link to the relevant telemetry setup doc near the top. +- Include a dashboard preview screenshot. +- Provide import instructions using `DashboardActions`. +- Include sections for what the dashboard monitors, metrics included, and next steps. + +### Troubleshooting Docs + +- Start with the specific problem and affected environments. +- Use symptom -> likely cause -> resolution -> verification. +- Prefer exact error strings or question-style titles for searchability. + +### User Guides + +- Use goal-oriented, end-to-end flows. +- Include expected results after major steps. +- End with next steps. + +### Explanation Docs + +- Focus on building a mental model. +- Use diagrams, examples, and scenarios. +- Link to how-to and reference docs instead of repeating them. + +### Reference Docs + +- Lead with the exact facts. +- Keep prose minimal. +- Use tables, lists, and short descriptions. + +### Sample Apps + +- Use correct SigNoz endpoints and link ingestion references. +- Document how to run locally and in Docker or Kubernetes when relevant. +- Include a `README.md` that points back to the relevant docs page. +- Add a "Validate in SigNoz" section. + +## Technical Verification + +For OpenTelemetry technical claims, verify against: + +1. `https://opentelemetry.io/docs/*` +2. `https://github.com/open-telemetry/*` + +## URLs, Redirects, And Discovery + +### URL Structure + +- Docs at `data/docs/<section>/<slug>.mdx` render to `/docs/<section>/<slug>/`. +- Blog posts at `data/blog/<slug>.mdx` render to `/blog/<slug>/`. +- This repo uses trailing slashes consistently. + +### Redirect Rules + +- Avoid changing URLs for live content unless necessary. +- If you rename or move a doc, add a permanent redirect in `next.config.js` under `async redirects()`. +- Update any affected internal links in the same PR. + +Example: + +```js +async redirects() { + return [ + { + source: '/docs/instrumentation/opentelemetry-cloudflare/', + destination: '/docs/instrumentation/cloudflare-workers/', + permanent: true, + }, + ] +} +``` + +### Sidebar Updates + +- When a doc should appear in docs navigation, update `constants/docsSideNav.ts`. +- Match the route to the rendered docs path. +- Add the entry in the most relevant existing section instead of creating duplicate navigation paths. + +### Discovery Surface Updates + +Some docs also need updates beyond the sidebar. Update discovery surfaces when a new page should appear in listicles, quick starts, overview cards, installation path cards, dashboard template listings, or similar surfaced integration collections. + +When needed: + +- Add or update the source data in the relevant `constants/componentItems/*.ts` file. +- Keep `constants/componentItems.ts` as the public barrel. +- Update the matching component `ICON_MAP` when required. + +### Tag Definitions + +If a docs change introduces a new frontmatter tag that needs a tooltip definition, update `constants/tagDefinitions.ts` in the same PR. + +### Redirect And Discovery Verification + +When redirects or discovery surfaces change, run: + +```bash +yarn check:doc-redirects +yarn test:doc-redirects +``` + +If `constants/componentItems/*.ts` changed, also run: + +```bash +yarn tsc --noEmit +node --test tests/component-items-sync.test.js +``` + +## Docs Author Checklist + +Use the PR snippet in [templates/pr-checklists.md#docs-changes](templates/pr-checklists.md#docs-changes) when preparing or reviewing docs work. + +- Frontmatter includes `date`, `id`, `title`, `description`, `doc_type`, and correct tags. +- Content matches the chosen `doc_type`. +- The primary job is clear and the happy path is easy to follow end to end. +- Steps are concise, minimal, and ordered for first success. +- Recommended defaults stay in the main flow; advanced options move to optional sections. +- `## Validate` shows exactly where success appears in SigNoz. +- `## Troubleshooting` maps symptom -> cause -> fix -> verification. +- Commands and snippets explain what to do, where to do it, and the expected result. +- Placeholders use `<...>` format and are documented. +- Links are helpful and validated. +- Images, if any, use the correct location and format. +- Redirect, sidebar, and discovery updates are handled when the doc URL changes or a new doc should appear in an existing surface. diff --git a/contributing/docs-review.md b/contributing/docs-review.md new file mode 100644 index 0000000000..5f3adc88c7 --- /dev/null +++ b/contributing/docs-review.md @@ -0,0 +1,202 @@ +# Docs Review + +Use this playbook when reviewing changes to `data/docs/**`, docs images, docs navigation, or docs discovery surfaces. + +Pair it with [docs-authoring.md](docs-authoring.md) for the underlying content standards. + +## Review Goals + +- Prioritize actionable findings over praise. +- Review from the reader's job-to-be-done first, then verify technical accuracy. +- Keep feedback specific, concise, and immediately actionable. +- Ignore date-only issues unless they block correctness or release process expectations. + +## Review Scope + +Review these when relevant: + +- `data/docs/**` +- `public/img/docs/**` +- `constants/docsSideNav.ts` +- `constants/componentItems.ts` +- `constants/componentItems/*.ts` +- `next.config.js` when docs URLs change + +If a PR also changes frontend code, use the frontend review workflow for the code portion. + +## Review Process + +1. Identify changed docs files. +2. Check whether related discovery files should also change. +3. Read the changed pages with the standards from [docs-authoring.md](docs-authoring.md) in mind. +4. Identify likely personas from context. +5. Run the JTBD-first rubric. +6. Verify technical claims when OpenTelemetry behavior or config is involved. +7. Leave inline findings only for real issues. +8. Post one concise summary comment. + +## JTBD-First Rubric + +Review each changed doc against these checks in order: + +1. Intended personas are clear from the content and assumptions. +2. The primary job is obvious and the page does not mix unrelated jobs in one mandatory flow. +3. The happy path is easy to follow end to end. +4. Time-to-first-success is short and the default path is clear. +5. Steps are concrete, concise, and unambiguous. +6. Only required actions stay in the main path. +7. Recommended defaults are the default, and advanced options are moved out of the main flow. +8. Critical prerequisites, attributes, or concepts have a direct step or high-value link. +9. Troubleshooting starts from symptoms and points to exact next actions. +10. Validation tells users what success looks like in SigNoz. +11. Next steps help users complete the broader job. +12. Links directly help readers complete the current step. +13. Added or edited links resolve and use canonical production paths. +14. Discovery surfaces are updated when the new doc should appear in an existing list or overview. + +If a check cannot be validated from the PR context, call out the assumption and residual risk. + +## Technical Accuracy + +When validating technical claims, use this source priority: + +1. `https://opentelemetry.io/docs/*` +2. `https://github.com/open-telemetry/*` +3. Other reputable sources only when official sources do not cover the claim + +Prioritize verification for: + +- config keys and component names +- receiver, exporter, and processor names +- environment variables and CLI flags +- APIs, semantic conventions, versions, and deprecations + +When a correction depends on verification: + +- include `Source: <URL>` in the finding +- keep citations precise +- avoid long quotes + +### Web Lookup Tips + +- Use targeted queries first (for example `site:opentelemetry.io <topic>`). +- Fetch only the minimal pages needed to verify the exact claim. +- Summarize findings; avoid large copy-paste. +- If sources conflict, prefer the most recent official OpenTelemetry docs or repo over third-party content. + +## Onboarding Label Policy + +This section is the canonical policy for `add-to-onboarding`. + +### Inspect PR File Status First + +Decide eligibility from PR file status, not just prose diff: + +```bash +gh api repos/<REPO>/pulls/<PR_NUMBER>/files --paginate +``` + +### Apply The Label Only When All Conditions Match + +Apply `add-to-onboarding` only when all of these are true: + +1. The PR adds at least one new docs file with `status == "added"`. +2. The new page's primary job is getting traces, logs, or metrics into SigNoz. +3. The new page includes concrete ingestion setup, such as: + - SigNoz endpoint instructions + - `signoz-ingestion-key` + - OTLP exporter environment variables + - direct SigNoz export steps + - equivalent "send data to SigNoz" instructions + +### Do Not Apply The Label For + +- edits to existing docs +- overview or concept pages +- dashboards or dashboard templates +- FAQs +- troubleshooting docs +- reference-only pages +- pages that mention ingestion but are not primarily about sending data to SigNoz + +### Examples + +- Apply: a new instrumentation or observability guide that walks users through exporting telemetry to SigNoz Cloud. +- Apply: a new logs page with SigNoz endpoint and auth setup. +- Skip: a migration guide that references SigNoz ingestion but focuses on moving from another vendor. +- Skip: an edit to an existing instrumentation page. + +### Apply, Remove, Or Report + +When a PR qualifies, try to add the label: + +```bash +gh issue edit <PR_NUMBER> --add-label "add-to-onboarding" +``` + +If a re-review shows the PR no longer qualifies and the label is present, remove it: + +```bash +gh issue edit <PR_NUMBER> --remove-label "add-to-onboarding" +``` + +If label changes fail because of permissions or actor restrictions: + +- do not fail the whole review +- report `recommended but permission denied` + +### Summary Comment Expectation + +Every docs review summary should include exactly one of: + +- `Onboarding label: applied` +- `Onboarding label: skipped` +- `Onboarding label: recommended but permission denied` + +When relevant, also include the matched file path and a one-line rationale. + +## Commenting Rules + +- Comment only on issues. +- Do not add praise-only comments. +- Include impact and a concrete fix suggestion. +- Use file references. +- Keep wording user-impact-focused. + +## Summary Format + +Post exactly one concise summary comment that includes: + +1. Findings grouped by severity (`P1`, `P2`, `P3`) +2. Intended personas and fit summary +3. JTBD coverage summary +4. Checklist coverage summary against [docs-authoring.md](docs-authoring.md) +5. Open questions or assumptions +6. The onboarding-label result + +## Suggested Commands + +```bash +# PR context +gh pr view <PR_NUMBER> +gh pr diff <PR_NUMBER> +gh api repos/<REPO>/pulls/<PR_NUMBER>/files --paginate + +# changed docs and guidance +rg --files data/docs +cat contributing/docs-authoring.md +cat contributing/docs-review.md + +# likely docs quality issues +rg -n "## Next steps|## Troubleshooting|KeyPointCallout|ToggleHeading|https?://|<[^>]+>" data/docs + +# link health +curl -sI <URL> +``` + +## Guardrails + +- Do not require a dedicated "Target Persona" section unless the doc truly needs it. +- Keep advanced options out of the mandatory path unless essential for first success. +- If a PR changes docs MDX components or component-driven patterns, verify `utils/docs/agentMarkdownStubs.ts` and `utils/docs/buildCopyMarkdownFromRendered.ts` behavior where relevant. +- Do not mark the review complete if the JTBD-first pass was skipped. diff --git a/contributing/repo-workflow.md b/contributing/repo-workflow.md new file mode 100644 index 0000000000..590a971810 --- /dev/null +++ b/contributing/repo-workflow.md @@ -0,0 +1,70 @@ +# Repo Workflow + +Use this playbook for the shared workflow across docs, blogs, site code, and reviews. + +## Local Setup + +- Install dependencies with `yarn install`. +- Start local development with `yarn dev`. +- Use `yarn build` before opening or updating a PR to catch MDX, TypeScript, and Contentlayer errors. + +## Shared Workflow + +1. Fork and clone the repo. +2. Create a focused feature branch. +3. Make task-scoped changes with clear commit messages. +4. Run the checks that match your change type. +5. Open the PR as Draft by default. +6. Mark it ready only after content/code and checks are complete. + +## Git Hooks And Checks + +- Husky installs Git hooks automatically on `yarn install` via the `prepare` script in `package.json`. +- Pre-commit runs `lint-staged` on staged files, which auto-fixes common JS, TS, MD, and MDX issues. +- When staged changes include docs or redirect-related files (`data/docs/**/*.mdx`, `next.config.js`, or `scripts/check-doc-redirects.js`), pre-commit also runs `yarn check:doc-redirects`. +- When staged changes include docs (`data/docs/**/*.mdx`), pre-commit also runs `yarn check:docs-metadata`. + +### Fixing Hook Failures + +- Lint or format issues: run `yarn lint`, review auto-fixes, and re-stage changed files. +- Redirect failures: run `yarn check:doc-redirects`, add the missing permanent redirect, then re-stage. +- Metadata failures: run `yarn check:docs-metadata`, fix the MDX frontmatter, then re-stage. +- Optional redirect test: run `yarn test:doc-redirects`. + +### Hooks Path + +- The repo uses Husky v9 defaults with `core.hooksPath=.husky`. +- If your local Git points somewhere else, run `git config core.hooksPath .husky` or rerun `yarn install`. + +### Bypass + +- `git commit --no-verify` is for emergencies only. Fix the underlying issue instead of relying on bypasses in normal work. + +## Verification Matrix + +- Docs changes (`data/docs/**`, docs images, docs nav, redirects/scripts): + - `yarn check:docs-metadata` + - `yarn check:doc-redirects` + - `yarn test:docs-metadata` + - `yarn test:doc-redirects` +- Site code changes (`app/**`, `components/**`, `hooks/**`, `utils/**`, config): + - `yarn lint` + - `yarn build` +- Mixed docs + code changes: + - run both sets +- `constants/componentItems/*.ts` changes: + - `yarn tsc --noEmit` + - `node --test tests/component-items-sync.test.js` + +## CI Checks + +- Docs Redirect Guard runs redirect tests and validation when docs paths or redirect-related files change. +- Docs Metadata Guard runs metadata tests and validation when docs files or metadata tooling changes. +- Add to Onboarding is label-driven. The eligibility policy lives in [docs-review.md](docs-review.md). + +## PR Expectations + +- Submit Draft PRs by default. +- Include a concise summary, clear motivation, and screenshots when the change is visual. +- Use the matching checklist snippets in [templates/pr-checklists.md](templates/pr-checklists.md). +- Report what you ran, what failed, and why. diff --git a/contributing/site-code.md b/contributing/site-code.md new file mode 100644 index 0000000000..5e34515de1 --- /dev/null +++ b/contributing/site-code.md @@ -0,0 +1,71 @@ +# Site Code + +Use this playbook when changing frontend or site code such as `app/**`, `components/**`, `hooks/**`, `utils/**`, `constants/**`, and related config. + +## Core Expectations + +- Prefer existing patterns and components before introducing new abstractions. +- Follow existing Next.js App Router conventions in the repo. +- Keep changes minimal and task-scoped. +- Avoid new dependencies unless they are clearly required. +- Report what you ran and what failed. + +## UI And Assets + +- Prefer `lucide-react` or `react-icons` for icons. +- If you need a custom brand or logo asset, place it under `public/svgs/**` and reference it via `/svgs/...`. +- Prefer existing primitives in `components/ui/**` for interactive UI. +- Avoid styling overrides unless they are necessary and consistent with existing Tailwind patterns. + +## Types, Constants, And Organization + +- Keep component-local types and constants in dedicated files when they are reused or meaningfully sized. +- Export shared pieces through folder `index.ts` files when that matches the existing pattern. +- Keep constants and helper shapes organized according to nearby code conventions. + +## Listicle And Discovery Data + +- Keep listicle and icon-card source data in `constants/componentItems/*.ts`, not inside React components. +- Treat `constants/componentItems.ts` as the public barrel only. +- Use one top-level export per source file. +- Use a flat `ComponentItem[]` for ungrouped surfaces. +- Use named sub-keys for grouped surfaces, such as `cloud: { aws, azure, gcp }`. +- When a grouped structure is used, also export a `getAll*()` helper that flattens every leaf array for shared consumers and tests. +- Never use hardcoded `slice()` boundaries to fake sections. +- After adding or removing items, update the relevant `ICON_MAP` and run: + +```bash +yarn tsc --noEmit +node --test tests/component-items-sync.test.js +``` + +## Async And DOM Safety + +- Prevent concurrent async invocations in click handlers by setting loading state before `await` or guarding with a ref. +- Be deliberate about DOM cleanup and transforms. +- When preparing rendered HTML for transforms such as HTML-to-Markdown, avoid redundant selectors and preserve cleanup order. + +## Docs Rendering Compatibility + +If a change affects docs MDX components or rendered docs output: + +- review agent markdown behavior in `utils/docs/agentMarkdownStubs.ts` +- keep `tests/agent-markdown-*.test.js` coverage up to date +- verify rendered Copy Markdown output through `utils/docs/buildCopyMarkdownFromRendered.ts` +- add or update targeted tests when practical + +## Dependency Policy + +- Do not add packages unless there is no suitable existing dependency. +- If you add one, justify it in the PR description and ensure it is actually used. + +## Verification + +For site code changes, run: + +```bash +yarn lint +yarn build +``` + +For mixed docs + site changes, also run the relevant docs checks from [repo-workflow.md](repo-workflow.md). diff --git a/contributing/templates/docs-frontmatter.md b/contributing/templates/docs-frontmatter.md new file mode 100644 index 0000000000..52ea508bfe --- /dev/null +++ b/contributing/templates/docs-frontmatter.md @@ -0,0 +1,18 @@ +# Docs Frontmatter Template + +```yaml +--- +date: <YYYY-MM-DD> # Use today's date or a date in last 7 days +id: <unique-id-or-slug> +title: <Title in Sentence Case> +description: <1-2 line summary with key terms> +doc_type: <howto|tutorial|reference|explanation> +# tags: +# - SigNoz Cloud +--- +``` + +Notes: + +- Omit `tags` when the doc applies to both Cloud and Self-Host. +- Use `tags: [Self-Host]` or `tags: [SigNoz Cloud]` only when the page is environment-specific. diff --git a/contributing/templates/docs-page.md b/contributing/templates/docs-page.md new file mode 100644 index 0000000000..45c4f44564 --- /dev/null +++ b/contributing/templates/docs-page.md @@ -0,0 +1,49 @@ +# Docs Page Template + +```md +## Overview + +<One to two lines on what this page helps the reader do.> + +<!-- Use the sections below only when they fit the doc_type. --> +<!-- For howto/tutorial pages, prefer prerequisites -> steps -> validate -> troubleshooting. --> +<!-- For reference/explanation pages, replace steps with lookup or concept sections. --> + +## Prerequisites (Optional) + +- <Required setup or access> + +## Steps / Main Sections + +### For howto/tutorial pages + +1. <Action> +2. <Action> +3. <Action> + +### For reference/explanation pages + +- <Exact fact, option, concept, trade-off, or lookup section> +- <Another section if needed> + +## Validate (Optional) + +- <Where to check in SigNoz> +- <What success looks like> + +## Troubleshooting (Optional) + +### <Symptom or error> + +- Likely cause: <cause> +- Fix: <action> +- Verify: <result> + +## Limitations (Optional) + +- <Constraint, caveat, or scope boundary> + +## Next steps (Optional) + +- <Related dashboard, alert, deeper guide, or reference page> +``` diff --git a/contributing/templates/pr-checklists.md b/contributing/templates/pr-checklists.md new file mode 100644 index 0000000000..e603590261 --- /dev/null +++ b/contributing/templates/pr-checklists.md @@ -0,0 +1,37 @@ +# PR Checklist Snippets + +Use the sections below as lightweight references when filling out or reviewing the PR template. + +## All Changes + +- Run the checks that match the files changed. +- Self-review the change before requesting review. +- Document any failures, caveats, or follow-up work. +- If a check is currently failing for unrelated repo or environment reasons, call that out clearly in the PR. + +## Docs Changes + +- Frontmatter is complete and correct. +- The primary job is clear and the happy path is easy to follow. +- `## Validate` shows where success appears in SigNoz. +- `## Troubleshooting` maps symptom -> cause -> fix -> verification. +- Links, images, redirects, and discovery updates are handled where needed. +- Relevant docs checks were run. + +## Blog Changes + +- Frontmatter includes `title`, `date`, `author`, and `tags`. +- Images live under `public/img/blog/<YYYY-MM>/`. +- Internal links use canonical production URLs. + +## Site Code Changes + +- Existing patterns and components were reused where possible. +- New dependencies are justified. +- Relevant lint, build, and targeted tests were run. + +## Renamed Or Moved Docs + +- Permanent redirect added in `next.config.js`. +- Internal links and sidebar entries updated. +- Redirect checks were run. diff --git a/contributing/templates/send-data-doc.md b/contributing/templates/send-data-doc.md new file mode 100644 index 0000000000..84341641b1 --- /dev/null +++ b/contributing/templates/send-data-doc.md @@ -0,0 +1,64 @@ +# Send Data Doc Template + +```mdx +## Overview + +<What telemetry this guide sends to SigNoz and for which technology> + +<!-- Mention OpenTelemetry in the title, slug, and overview. --> +<!-- Use direct export to SigNoz Cloud as the primary path. --> + +<KeyPointCallout title="Using self-hosted SigNoz?" defaultCollapsed={true}> + Most steps are identical. Update the endpoint and remove the ingestion key + header as shown in [Cloud -> + Self-Hosted](https://signoz.io/docs/ingestion/cloud-vs-self-hosted/#cloud-to-self-hosted). +</KeyPointCallout> + +## Prerequisites + +- <Access, runtime, package, or environment prerequisites> + +## Steps + +<!-- If VM, Kubernetes, Docker, or Windows materially differ, split the flow with Tabs/TabItem. --> +<!-- Keep the happy path minimal and platform-specific only where necessary. --> + +1. <Install or configure OpenTelemetry> +2. <Add direct export to SigNoz Cloud> +3. <Run or restart the app> + +<!-- For Collector config, show only the snippet to append and tell users where to enable it. --> +<!-- Do not present a full otel-collector-config.yaml replacement unless the page is explicitly a full clean-room setup. --> + +## Validate + +- <Where traces, logs, or metrics should appear in SigNoz> +- <What success looks like> + +<details> +<ToggleHeading> +## Troubleshooting +</ToggleHeading> + +### <Symptom or error> + +- Likely cause: <cause> +- Fix: <action> +- Verify: <result> + +</details> + +<details> +<ToggleHeading> +## Setup OpenTelemetry Collector (Optional) +</ToggleHeading> + +<Explain when to use the Collector and link to the switch-to-collector guide.> +<Show only the config snippet to append and the pipeline change required to enable it.> + +</details> + +## Next steps + +- <Dashboard, alerting, trace, or deeper guide links> +``` diff --git a/contributing/templates/troubleshooting-page.md b/contributing/templates/troubleshooting-page.md new file mode 100644 index 0000000000..1a2ae17adf --- /dev/null +++ b/contributing/templates/troubleshooting-page.md @@ -0,0 +1,25 @@ +# Troubleshooting Template + +```md +## Overview + +<Problem statement and affected environment> + +## Symptoms + +- <Visible symptom> + +## Likely causes + +- <Cause 1> +- <Cause 2> + +## Resolution + +1. <Fix step> +2. <Fix step> + +## Verify + +- <How to confirm the issue is resolved> +``` diff --git a/data/docs/contributing.mdx b/data/docs/contributing.mdx index b5ab88ddf6..e5023d75b5 100644 --- a/data/docs/contributing.mdx +++ b/data/docs/contributing.mdx @@ -1,9 +1,25 @@ --- -date: 2024-06-06 +date: 2026-03-24 id: contributing -title: Contribution Guidelines +title: Contributing to SigNoz +description: Learn how to contribute across the SigNoz GitHub organization, including the main SigNoz repo, dashboard templates, website docs, and other open source repos. +doc_type: reference --- ## Welcome to SigNoz Contributing section 🎉 -Please check [CONTRIBUTING.md](https://github.com/SigNoz/signoz/blob/main/CONTRIBUTING.md) for instructions on how to contribute to SigNoz. \ No newline at end of file +SigNoz contributions span multiple repositories under the <a href="https://github.com/SigNoz" target="_blank" rel="noopener noreferrer nofollow">SigNoz GitHub organization</a>. + +Start by choosing the repository you want to contribute to, then follow that repository's local contribution guide, README, issue templates, and code review process. + +Common starting points: + +- Main SigNoz product repo: <a href="https://github.com/SigNoz/signoz" target="_blank" rel="noopener noreferrer nofollow">github.com/SigNoz/signoz</a> +- Dashboard templates repo: <a href="https://github.com/SigNoz/dashboards" target="_blank" rel="noopener noreferrer nofollow">github.com/SigNoz/dashboards</a> +- Website and docs repo: <a href="https://github.com/SigNoz/signoz.io" target="_blank" rel="noopener noreferrer nofollow">github.com/SigNoz/signoz.io</a> + +If you want to contribute to the SigNoz website, docs, blog, or review workflows specifically, use the website repo's contributor guide: + +- <a href="https://github.com/SigNoz/signoz.io/blob/main/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer nofollow">signoz.io/CONTRIBUTING.md</a> + +For issues, feature requests, or discussions, check the relevant repository in the SigNoz organization first so your contribution lands in the right place. diff --git a/tests/component-items-sync.test.js b/tests/component-items-sync.test.js index aaf4c86fa1..469be9d3b3 100644 --- a/tests/component-items-sync.test.js +++ b/tests/component-items-sync.test.js @@ -80,6 +80,9 @@ const walkLeafArrays = (value, path = []) => { ) } +const isValidHref = (href) => + typeof href === 'string' && (href.startsWith('/') || href.startsWith('https://')) + test('all flat item arrays are non-empty', () => { for (const name of FLAT_EXPORTS) { const items = componentItems[name] @@ -112,11 +115,8 @@ test('all items have valid name, href, and clickName', () => { `${name}[${i}].name should be a non-empty string, got: ${JSON.stringify(item.name)}` ) assert.ok( - typeof item.href === 'string' && - (item.href.startsWith('/docs/') || - item.href.startsWith('https://') || - item.href.startsWith('/docs')), - `${name}[${i}].href should start with /docs/ or https://, got: ${JSON.stringify(item.href)}` + isValidHref(item.href), + `${name}[${i}].href should start with / or https://, got: ${JSON.stringify(item.href)}` ) assert.ok( typeof item.clickName === 'string' && item.clickName.trim().length > 0,