docs(rules): read authoring guide before writing rules#117
docs(rules): read authoring guide before writing rules#117zolotokrylin wants to merge 3 commits into
Conversation
Time Submission Status
Submit or update total time with: Add time on top of previous submission with: See available commands to help comply with our Guidelines. |
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
zolotokrylin
force-pushed
the
docs/rules-authoring-guide
branch
from
e84e5ef to
38dcdc8
Compare
| Followed by the rule body: | ||
|
|
||
| ```markdown | ||
| ## [Rule title repeated as heading] |
There was a problem hiding this comment.
why this is H2 and not H1?
| depends_on: "XXX-NNN" # optional — ID of the rule that must be applied first | ||
| enforcement: "manual" | ||
| severity: "error" | ||
| problem: "One-line statement of the situation this rule addresses" # optional |
There was a problem hiding this comment.
Note: must be under 60 chars
| What goes wrong when this rule is not followed. Be concrete — name the | ||
| failure mode, not an abstract risk. |
There was a problem hiding this comment.
must be 360 chars max
| What to do. Use numbered steps for sequential actions, bullets for | ||
| independent items. Be specific enough that a new team member can apply | ||
| it without asking for clarification. |
There was a problem hiding this comment.
must be 360 chars max
| - [ ] Another checkable item | ||
| ``` | ||
|
|
||
| `Acceptance Criteria` is optional but strongly recommended for rules that |
There was a problem hiding this comment.
each step must be atomic
|
|
||
| - Each repo has its own prefix (e.g. `SAL-` for `holdex/partners`, | ||
| `HR-` for `holdex/hr-internal`, `DEV-` for `holdex/developers`) | ||
| - IDs increment by 10 (`DEV-010`, `DEV-020`) to leave room for insertion |
| ## For Contributors | ||
|
|
||
| If you are adding or updating documentation in this or any other Holdex repo, | ||
| read [How to Create and Manage Rules](./docs/RULES.md) to understand the | ||
| difference between rules, specs, and end-user docs, and how to author each. |
There was a problem hiding this comment.
Contributors are developers.
This needs to be factored into contributing.md
1 participant
Adds docs/RULES.md — the canonical guide for creating and managing rules
across all Holdex repos.
Covers:
Linked from the README under a new "For Contributors" section.