From 99d963803de161b8b7ac0ebd5e72f726704bbffd Mon Sep 17 00:00:00 2001 From: Jonah Kowall Date: Fri, 26 Dec 2025 07:37:56 -0600 Subject: [PATCH 1/3] docs: add detailed agent instructions for testing and spellchecking - Add section on testing and verifying changes locally - Add spellchecking guidance with dictionary setup - Add documentation versioning guidelines - Reference human-centric guidelines (DCO, PR etiquette) to CONTRIBUTING.md - Add troubleshooting sections Signed-off-by: Jonah Kowall --- AGENTS.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 94 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 09dcc2f3..b8bfa8a2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,10 @@ Before making changes, familiarize yourself with: The CONTRIBUTING.md file contains all necessary information for setting up, building, linting, and making changes to the documentation. +**For human-centric guidelines** such as DCO (Developer Certificate of Origin) +signing, PR etiquette, and community interaction, refer to [CONTRIBUTING.md](CONTRIBUTING.md) +and the [general contributing guidelines](https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING_GUIDELINES.md). + ## Agentic Workflow Tips ### Repository Structure @@ -41,6 +45,79 @@ efficiently: - **Deployment**: Netlify automatically deploys from the `main` branch - **Preview**: Netlify creates preview deployments for PRs +### Testing and Verifying Changes + +Before submitting a PR, verify your changes locally: + +#### 1. Setup (First Time Only) + +```bash +npm install +``` + +This installs all dependencies including the required Hugo version. + +#### 2. Run the Site Locally + +```bash +make develop +# or +npm run serve +``` + +This starts a local server at [localhost:1313](http://localhost:1313) with hot +reload. Verify your changes render correctly in the browser. + +#### 3. Build the Site + +```bash +npm run build +``` + +Ensure the build completes without errors before submitting a PR. + +#### 4. Run All Checks + +Run these commands to verify CI will pass: + +```bash +npm run check:format # Check code formatting +npm run check:spelling # Run spellcheck +npm run check:links:internal # Check internal links (faster) +npm run check:filenames # Check filename conventions +``` + +For comprehensive link checking (including external links): + +```bash +npm run check:links:all # Check all links (slower, builds site first) +``` + +#### 5. Fix Common Issues + +```bash +npm run fix:format # Auto-fix formatting issues +npm run fix:filenames # Convert underscores to hyphens in filenames +npm run fix # Run both fixes +``` + +### Spellchecking + +The repository uses [cspell](https://cspell.org/) for spellchecking. Configuration +is in `.cspell.yml` with custom dictionaries in the `.cspell/` directory. + +If the spellchecker flags a legitimate word (technical term, proper noun, etc.): + +1. **For general technical terms**: Add to `.cspell/project-words.txt` +2. **For people's names**: Add to `.cspell/project-names-src.txt` + +**Important rules for `project-words.txt`:** + +- Words must be sorted alphabetically (case-insensitive) +- One word per line +- The file is case-sensitive, so add the exact casing needed +- Run `sort -c --ignore-case .cspell/project-words.txt` to verify sorting + ### Troubleshooting #### Link Checker Issues @@ -61,11 +138,24 @@ Common issues: #### Filename Violations -If CI complains about filename conventions: +Run `npm run fix:filenames` to auto-fix. -```bash -npm run fix:filenames -``` +#### Spellcheck Failures + +1. Review the flagged words in the output +2. If the word is misspelled, fix it in the content +3. If the word is legitimate, add it to the appropriate dictionary file +4. Ensure `project-words.txt` remains sorted alphabetically + +### Documentation Versioning + +When making documentation changes: + +- **New features/changes**: Edit files in `content/docs/v2/_dev/` (for next release) +- **Fixes for current version**: Apply to both `_dev/` and the most recent version + directory (e.g., `content/docs/v2/2.x/`) so changes appear immediately on the + live site +- **Backporting**: Update older version directories if the fix applies to them ### Additional Resources From 9516d559ba403a1e977905df4148bb0ebb75c5cc Mon Sep 17 00:00:00 2001 From: Jonah Kowall Date: Sun, 8 Feb 2026 08:16:34 +0300 Subject: [PATCH 2/3] Fix: Disable edit links for unreleased versions (#1065) This change disables the 'Edit this page', 'View page source', and 'Create child page' links for pages within the '_dev' directory (unreleased versions). This prevents broken links (404) in CI checks for new documentation files that do not yet exist on the main branch. It also updates .htmltest.yml to enable checking of edit links for released versions, ensuring no regressions. Fixes #1065 Signed-off-by: Jonah Kowall --- .htmltest.yml | 3 +- .../layouts/_partials/page-meta-links.html | 55 +++++++++++++++++++ 2 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 themes/docsy-overrides/layouts/_partials/page-meta-links.html diff --git a/.htmltest.yml b/.htmltest.yml index 4594e728..ff7abad9 100644 --- a/.htmltest.yml +++ b/.htmltest.yml @@ -9,8 +9,7 @@ IgnoreURLs: - ^/docs/latest(/?|/architecture/)$ - /livereload.js # cSpell:disable-line - ^https://www.jaegertracing.io/js/lunr - # Ignore Docsy-generated GitHub links for now - - ^https?://github\.com/.*?/.*?/(new|edit)/ # view-page, edit-source etc + # Valid URL, whether canonical (before reorg) or not (and handled via a redirect) - ^/docs/1.[6-9]\d/sampling/ # Valid URLs, but servers yield 403 or similar errors diff --git a/themes/docsy-overrides/layouts/_partials/page-meta-links.html b/themes/docsy-overrides/layouts/_partials/page-meta-links.html new file mode 100644 index 00000000..802e6c5f --- /dev/null +++ b/themes/docsy-overrides/layouts/_partials/page-meta-links.html @@ -0,0 +1,55 @@ +{{/* cSpell:ignore querify subdir */ -}} +{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} + +{{ if .File -}} +{{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} +{{ $gh_repo := $.Param "github_repo" -}} +{{ $gh_url := $.Param "github_url" -}} +{{ $gh_subdir := $.Param "github_subdir" | default "" -}} +{{ $gh_project_repo := $.Param "github_project_repo" -}} +{{ $gh_branch := $.Param "github_branch" | default "main" -}} +{{ $is_unreleased := in $path "_dev" -}} +
+{{ if $gh_url -}} + {{ warnf "Warning: use of `github_url` is deprecated. For details, see https://www.docsy.dev/docs/content/repository-links/#github_url-optional" -}} + {{ T "post_edit_this" }} +{{ else if $gh_repo -}} + + {{/* Adjust $path based on path_base_for_github_subdir */ -}} + {{ $ghs_base := $.Param "path_base_for_github_subdir" -}} + {{ $ghs_rename := "" -}} + {{ if reflect.IsMap $ghs_base -}} + {{ $ghs_rename = $ghs_base.to -}} + {{ $ghs_base = $ghs_base.from -}} + {{ end -}} + {{ with $ghs_base -}} + {{ $path = replaceRE . $ghs_rename $path -}} + {{ end -}} + + {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}} + {{ $gh_repo_path = replaceRE "//+" "/" $gh_repo_path -}} + + {{ $viewURL := printf "%s/tree/%s" $gh_repo $gh_repo_path -}} + {{ $editURL := printf "%s/edit/%s" $gh_repo $gh_repo_path -}} + {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}} + {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} + {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} + {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} + + {{ if not $is_unreleased -}} + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ end -}} + {{ T "post_create_issue" }} + {{ with $gh_project_repo -}} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} + {{ end -}} + +{{ end -}} +{{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} + {{ T "print_entire_section" }} +{{ end }} +
+{{ end -}} From 12ef2fa4e6aae7aeb581ffd25c7489aafa4dc13a Mon Sep 17 00:00:00 2001 From: Jonah Kowall Date: Sun, 8 Feb 2026 13:19:30 +0300 Subject: [PATCH 3/3] Fix: Point edit links to GITHUB_SHA/HEAD in CI Addressing feedback from @yurishkuro: - Reverted the logic that disabled links for _dev versions. - Updated page-meta-links.html to use GITHUB_SHA (Actions) or HEAD (Netlify) environment variables when running in CI. This ensures edit links point to the commit/branch being tested, making them valid for new files introduced in PRs. - Updated hugo.yaml to whitelist GITHUB_SHA and HEAD in the security.funcs.getenv policy. Signed-off-by: Jonah Kowall --- hugo.yaml | 10 ++++ .../layouts/_partials/page-meta-links.html | 50 ++++++++++--------- 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/hugo.yaml b/hugo.yaml index 02884df0..0787c917 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -156,3 +156,13 @@ module: target: assets/icons/logo.svg - source: static/img/hero-background.jpg target: content/hero-background.jpg + +security: + funcs: + getenv: + # Defaults + - ^HUGO_ + - ^CI$ + # Whitelist for PR link checking + - ^GITHUB_SHA$ + - ^HEAD$ diff --git a/themes/docsy-overrides/layouts/_partials/page-meta-links.html b/themes/docsy-overrides/layouts/_partials/page-meta-links.html index 802e6c5f..d787fbb5 100644 --- a/themes/docsy-overrides/layouts/_partials/page-meta-links.html +++ b/themes/docsy-overrides/layouts/_partials/page-meta-links.html @@ -1,6 +1,3 @@ -{{/* cSpell:ignore querify subdir */ -}} -{{/* Class names ending with `--KIND` are deprecated in favor of `__KIND`, but we're keeping them for a few releases after 0.9.0 */ -}} - {{ if .File -}} {{ $path := strings.TrimPrefix (add hugo.WorkingDir "/") $.File.Filename -}} {{ $gh_repo := $.Param "github_repo" -}} @@ -8,22 +5,23 @@ {{ $gh_subdir := $.Param "github_subdir" | default "" -}} {{ $gh_project_repo := $.Param "github_project_repo" -}} {{ $gh_branch := $.Param "github_branch" | default "main" -}} -{{ $is_unreleased := in $path "_dev" -}} +{{/* Use GITHUB_SHA (Actions) or HEAD (Netlify) if in CI, to link to the correct commit/branch for new files */}} +{{ if os.Getenv "CI" -}} +{{ $gh_branch = os.Getenv "GITHUB_SHA" | default (os.Getenv "HEAD") | default $gh_branch -}} +{{ end -}} +
-{{ if $gh_url -}} - {{ warnf "Warning: use of `github_url` is deprecated. For details, see https://www.docsy.dev/docs/content/repository-links/#github_url-optional" -}} - {{ T "post_edit_this" }} -{{ else if $gh_repo -}} + {{ if $gh_repo -}} {{/* Adjust $path based on path_base_for_github_subdir */ -}} {{ $ghs_base := $.Param "path_base_for_github_subdir" -}} {{ $ghs_rename := "" -}} {{ if reflect.IsMap $ghs_base -}} - {{ $ghs_rename = $ghs_base.to -}} - {{ $ghs_base = $ghs_base.from -}} + {{ $ghs_rename = $ghs_base.to -}} + {{ $ghs_base = $ghs_base.from -}} {{ end -}} {{ with $ghs_base -}} - {{ $path = replaceRE . $ghs_rename $path -}} + {{ $path = replaceRE . $ghs_rename $path -}} {{ end -}} {{ $gh_repo_path := printf "%s/%s/%s" $gh_branch $gh_subdir $path -}} @@ -36,20 +34,24 @@ {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} - {{ if not $is_unreleased -}} - {{ T "post_view_this" }} - {{ T "post_edit_this" }} - {{ T "post_create_child_page" }} - {{ end -}} - {{ T "post_create_issue" }} + {{ T "post_view_this" }} + {{ T "post_edit_this" }} + {{ T "post_create_child_page" }} + {{ T "post_create_issue" }} {{ with $gh_project_repo -}} - {{ $project_issueURL := printf "%s/issues/new" . -}} - {{ T "post_create_project_issue" }} + {{ $project_issueURL := printf "%s/issues/new" . -}} + {{ T "post_create_project_issue" }} {{ end -}} -{{ end -}} -{{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} - {{ T "print_entire_section" }} -{{ end }} + {{ end -}} + {{ with .CurrentSection.AlternativeOutputFormats.Get "print" -}} + {{ T "print_entire_section" + }} + {{ end }}
-{{ end -}} +{{ end -}} \ No newline at end of file