Skip to content

docs: refresh AGENTS.md conventions and fix stale guidance - #321

Merged
wrn14897 merged 3 commits into
mainfrom
warren/update-agents-doc
Nov 17, 2026
Merged

wrn14897 merged 3 commits into
mainfrom
warren/update-agents-doc

Conversation

@wrn14897

@wrn14897 wrn14897 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Updates AGENTS.md to match the repo:

  • Branch naming: prefix with the author's name or handle instead of hardcoded warren/.
  • PR titles: conventional-commit style (Kodiak squash-merges with the PR title as the commit subject, so the old [HDX-<ticket>] rule conflicted with the commit convention). Ticket link only when there is one.
  • Pre-commit hook: runs make docs-check (not make docs), also triggers on Chart.yaml, and skips without helm.
  • helm-docs: only # -- comments are published; removed the conflicting "document all values with inline comments" line.
  • Removed the nonexistent tests/__snapshot__/ reference.
  • Added templates/otel-collector/, the additionalManifests top-level key, and the Node.js/npm requirement for the full-stack integration suite.
  • CI table: real workflow names, the missing upgrade-notes, lint-workflows, deep-review, and external-contributor-alerts workflows, the version-script-smoke job, and the correct release trigger.
  • Smaller fixes: yarn changeset, the tpl example points at _helpers.tpl, shell examples point at scripts that follow the convention, and Key File Locations lists files instead of commands.

Docs-only change; no changeset needed.

@wrn14897
wrn14897 requested a review from a team as a code owner November 17, 2026 15:45
@changeset-bot

changeset-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: f405b9c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

Helm template coverage

Metric Value
Line coverage 99.85%
Branch coverage 91.00%
Line threshold 99% (met)
Branch threshold 90% (met)
Uncovered details

charts/clickstack/templates/NOTES.txt

Uncovered lines: none

Uncovered branches: 37:default:fallback

charts/clickstack/templates/_helpers.tpl

Uncovered lines: 17

Uncovered branches: 130:range:empty, 132:range:empty, 133:ternary:false, 16:if:true, 194:or(1):true, 211:range:empty, 242:default:fallback, 243:or(1):true, 259:if:false, 327:range:empty, 348:range:empty

charts/clickstack/templates/additional-manifests.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/clickhouse/cluster.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/clickhouse/keeper.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/configmap.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/cronjob-check-alerts.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/dashboard-configmap.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/hyperdx/dashboard-provisioner-rbac.yaml

Uncovered lines: none

Uncovered branches: 40:range:empty

charts/clickstack/templates/hyperdx/deployment.yaml

Uncovered lines: none

Uncovered branches: 121:default:fallback, 131:default:fallback, 196:default:fallback, 201:with:empty, 20:with:empty, 26:default:fallback, 41:if:false, 42:with:empty

charts/clickstack/templates/hyperdx/hpa.yaml

Uncovered lines: none

Uncovered branches: 16:with:empty

charts/clickstack/templates/hyperdx/ingress.yaml

Uncovered lines: none

Uncovered branches: 35:if:false, 40:range:empty, 45:range:empty, 48:with:empty, 54:range:empty, 58:range:empty, 59:or(2):true, 59:or(3):true

charts/clickstack/templates/hyperdx/networkpolicy.yaml

Uncovered lines: none

Uncovered branches: 11:with:empty

charts/clickstack/templates/hyperdx/pdb.yaml

Uncovered lines: none

Uncovered branches: 10:with:empty

charts/clickstack/templates/hyperdx/secret.yaml

Uncovered lines: none

Uncovered branches: 1:or(2):true, 1:or(3):true

charts/clickstack/templates/hyperdx/service.yaml

Uncovered lines: none

Uncovered branches: 14:default:fallback, 9:with:empty

charts/clickstack/templates/hyperdx/serviceaccount.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/mongodb/community.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/mongodb/password-secret.yaml

Uncovered lines: none

Uncovered branches: none

charts/clickstack/templates/otel-collector/custom-config.yaml

Uncovered lines: none

Uncovered branches: none

@wrn14897 wrn14897 changed the title docs: use author name as branch prefix in AGENTS.md docs: use author name or handle as branch prefix in AGENTS.md Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Deep Review

Documentation-only change to AGENTS.md that refreshes repo conventions and removes stale guidance. Every factual claim in the diff was verified against the working tree: Makefile targets (docs, docs-check), the .githooks/pre-commit logic, scripts/helmdocs.sh (--ignore-non-descriptions), templates/otel-collector/, the additionalManifests values key, all nine workflow display names and triggers, the version-script-smoke job, the release.yml workflow_run trigger, the clickstack.hyperdx.configmap tpl helper, yarn changeset, and the referenced script/file paths. All check out. The removed tests/__snapshot__/ reference is correct — no snapshot directory exists.

The two prior PR comments are automated bot output (changeset-bot, helmcov); neither is human feedback requiring action. The changeset-bot "no changeset found" warning is consistent with the repo convention that changesets cover user-facing chart changes, not docs.

✅ No critical issues found.

No P2 issues. The remaining items are minor accuracy refinements in a doc whose purpose is accuracy.

🔵 P3 nitpicks (2)
  • AGENTS.md:134 — the CI table lists the Lint Workflows trigger as "push/PR to main touching workflows", but lint-workflows.yml gates on the broader .github/** path filter, so it also fires on non-workflow changes under .github/.
    • Fix: change "touching workflows" to "touching .github/**".
  • AGENTS.md:30 — the pre-commit description lists Chart.yaml, values.yaml, templates, and README templates as make docs-check triggers, omitting scripts/helmdocs.sh and scripts/install-helm-docs.sh, which the hook also treats as docs changes.
    • Fix: note that changes to the helm-docs scripts also trigger the docs check, or qualify the list as representative.

Reviewers (5): correctness, project-standards, maintainability, testing, previous-comments.

Testing gaps: None — docs-only change introduces no chart behavior requiring helm-unittest coverage.

No finding blocks merge automatically. A maintainer will expect P0/P1 findings in code this PR changes to be fixed; P2/P3 are your call -- fix or reply. Never fix findings about surrounding code here; reply instead. Do not widen the PR.

karl-power
karl-power previously approved these changes Nov 17, 2026
@wrn14897 wrn14897 changed the title docs: use author name or handle as branch prefix in AGENTS.md docs: refresh AGENTS.md conventions and fix stale guidance Nov 17, 2026
@wrn14897
wrn14897 enabled auto-merge (squash) November 17, 2026 15:58
@wrn14897
wrn14897 merged commit ba872ba into main Nov 17, 2026
11 checks passed
@wrn14897
wrn14897 deleted the warren/update-agents-doc branch November 17, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants