docs(contributing): refactor contributor guidance into playbooks#2958
docs(contributing): refactor contributor guidance into playbooks#2958
Conversation
… organization Refined contribution guidelines for adding listicle items: - Treat `constants/componentItems.ts` as barrel/export file only, move source data to `constants/componentItems/*.ts` - Clarify when to use flat lists vs sectioned objects with `getAll*()` helpers - Emphasize using named keys instead of `slice()` to prevent silent data shifts - Add verification command `node --test tests/component-items-sync.test.js` - Improve markdown formatting with blank lines for better readability
Updated the documentation for PR review processes to clarify the criteria for applying the `add-to-onboarding` label. Key changes include: - Detailed conditions for labeling based on new documentation files and their relevance to SigNoz data ingestion. - Added examples of when to apply or skip the onboarding label. - Specified handling of permission issues when applying labels during reviews. - Improved instructions for using the GitHub API to inspect PR file statuses.
Enhanced the contribution documentation by: - Clarifying the use of `CONTRIBUTING.md` as the entry point and introducing specific playbooks under `contributing/**` for detailed guidance. - Updating the agent skills to reference the new playbooks for PR reviews, ensuring consistency in documentation standards. - Adding a new `blog-workflow.md` for blog contributions and a `docs-authoring.md` for product documentation authoring standards. - Streamlining the onboarding label policy and review processes to align with the new structure.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
makeavish
requested review from
a team,
pranay01 and
therealpandey
as code owners
|
Claude finished @makeavish's task in 3m 58s —— View job PR Review: docs(contributing) — refactor contributor guidance into playbooks
FindingsP2 — Repo name mismatch in absolute URLs P2 — Verification matrix duplicated in 3 places P3 — Personas and fitThis PR targets contributors, reviewers, and coding agents. The new layered structure (slim root JTBD coverageThe refactor achieves its stated job: replace monolithic guidance with a task router. The playbooks are well-structured and internally consistent. The JTBD-first rubric, onboarding-label policy, and doc-type guidance are all properly placed in their respective playbooks. Checklist coverage
Open questions
Onboarding label: skippedThis PR edits an existing docs page and adds repo-internal contributor guidance — not a new send-data page. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
- Consolidated the verification matrix into a single reference in `contributing/repo-workflow.md`. - Updated links in `AGENTS.md`, `CONTRIBUTING.md`, and `contributing.mdx` to point to the new repository URL `signoz.io`. - Streamlined the verification process instructions for clarity and consistency across documentation.
3 participants
Summary
Refactor contributor guidance into a layered, task-based system with a slim root
CONTRIBUTING.mdand canonical playbooks undercontributing/.Motivation / Problem
CONTRIBUTING.mdhad become a monolithic source for contributors, reviewers, agents, and workflow prompts, which made it hard to scan and easy to duplicate or drift.Changes
CONTRIBUTING.mdwith a short task router and added focused playbooks/templates undercontributing/AGENTS.md, PR template, review skills, and GitHub workflow prompts to consume the canonical playbooks instead of duplicating policy/docs/contributing/page organization-wide while pointingsignoz-web-specific contributors to the repo-local guideDescription
This PR centralizes detailed contributor policy into repo-internal playbooks, keeps the root contributor guide stable and easier to skim, and aligns reviewers/agents/workflows on the same source of truth. It also includes the earlier branch changes for onboarding label guidance and
componentItemshref validation in the sync test.Type of Change
data/docs/**data/blog/**app/**,components/**,hooks/**,utils/**, config, etc.next.config.jsredirectsImpact
If breaking change, describe migration steps:
Context & Screenshots
No UI changes.
Before / After (if applicable)
Before: one large
CONTRIBUTING.mdcarried most contributor, reviewer, and agent policy.After:
CONTRIBUTING.mdis the entrypoint, and detailed policy lives undercontributing/.Checklist
General
maintype: description)For all changes
yarn build) with no errorsyarn lintand fixed any issuesyarn check:doc-redirects/yarn check:docs-metadataif applicable)For docs changes (
data/docs/**)constants/docsSideNav.tsif adding or moving a docFor blog changes
title,date,author,tags(andcanonicalUrlif applicable)public/img/blog/<YYYY-MM>/For site code changes
For renamed or moved docs
next.config.jsunderasync redirects()constants/docsSideNav.tsyarn check:doc-redirectsto verifyTesting
Steps to test:
yarn check:docs-metadatayarn check:doc-redirectsyarn test:docs-metadatayarn test:doc-redirectsnode --test tests/component-items-sync.test.jsyarn tsc --noEmitThis branch also contains the earlier commits that:
tests/component-items-sync.test.jshref validation to allow root-relative links