docs: add a developer primer - #36
Conversation
Add docs/primer/README.md, a concise onboarding guide that teaches a new developer what Vaar is, how a lint run flows through the packages and how to run it. The primer follows the GitHub CLI primer's Foundations / Components / Getting Started shape and links out to the existing reference docs. Every command and output shown was produced against a local build. Link it from the README Documentation section. Closes envaar#9 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughVaar adds a developer primer covering its foundations, internal lint pipeline, build verification, CLI behavior, fixes, rule and scope selection, and related references. The main README links new developers to the primer. ChangesVaar Primer Documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/primer/README.md`:
- Around line 132-135: Update all clone-based command examples to invoke the
built binary consistently: use ./bin/vaar in docs/primer/README.md lines
132-135, 157-159, 177-180, and 191-194, including the JSON, fix, rule-selection,
and scope-selection examples.
- Around line 118-119: Update the output grammar description near the documented
severity/rule/file/message format to account for --fix runs: either scope the
existing format to non---fix output or document the optional “[fixed]” prefix
while preserving the clean-run and exit-code statements.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: b5fc50ae-0255-4c01-991e-cc69bd7341b8
📒 Files selected for processing (2)
README.mddocs/primer/README.md
…mmar Addresses CodeRabbit review on envaar#36. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Both addressed: the output-grammar line now mentions the |
…mmar Addresses CodeRabbit review on envaar#36. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new developer primer under docs/primer/ and links to it from the root README to help new contributors understand Vaar’s architecture and run-flow quickly, per Issue #9 (modeled after the GitHub CLI primer structure).
Changes:
- Add
docs/primer/README.mdas a hands-on, ~10-minute walkthrough covering Foundations, Components, Getting Started, and Next Steps. - Update root
README.mdDocumentation section to link to the new Primer for onboarding.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| README.md | Adds a discoverable link to the new developer primer from the Documentation section. |
| docs/primer/README.md | Introduces the new onboarding primer, including architecture mapping and practical CLI examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3e7502f to
f2e09dd
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/primer/README.md`:
- Around line 100-101: Correct the PATH guidance in the examples section: do not
instruct users to add the executable path `./bin/vaar` or a repository-relative
`./bin` directory. Show a usable absolute PATH export targeting the Vaar clone’s
bin directory, or keep `./bin/vaar` explicitly in every command example.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: c02110e0-a5d4-46c8-8233-b3ea5e817945
📒 Files selected for processing (2)
README.mddocs/primer/README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- README.md
PATH entries must be directories, so pointing readers at ./bin/vaar (and implicitly a relative ./bin, which resolves inside the linted repository) never made the bare vaar invocations work. Show an absolute export from the Vaar clone instead. Also reword "can take the Primer" to "can read the Primer" in the root README. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
CodeRabbit's PATH catch was right — the note I added earlier pointed |
✅ Action performedFull review finished. |
Fixes #9.
Adds
docs/primer/README.md— a ~10-minute hands-on tour with the issue's requested sections (Foundations, Components, Getting Started, plus Where To Go Next), following the structure of the GitHub CLI primer the issue references (kept as one well-organized file since the content fits; happy to split into per-section files if you prefer that shape). One link line added to the README's Documentation paragraph.Truthfulness bar: every command shown was executed against a locally built
./bin/vaarand every output block is real (trimmed) output from those runs against the repo's broken example; every flag mentioned exists inlint --helpon current main. Notably the primer documents-o/--output(present and working, though absent from the lint guide — #23/#31 territory) and deliberately omits--list-rules(only exists in the open #30, not on main yet).Components are mapped to their actual packages (
cmd/vaar,internal/cli|fs|envfile|lint|lint/rules|report) and the run-flow description followsRunnerininternal/lint/runner.go.Gates:
make lint/vet/buildgreen (docs-only; the two chmod-0-as-root cli tests fail on clean main too, invisible to CI).AI assistance disclosure
Written with AI assistance (Claude); all commands, outputs, and flags were verified against the real binary before opening.
Summary by CodeRabbit
.envlinting), core principles, the fullvaar lintworkflow (rule selection, scoping, findings, optional--fixwith re-check), and guidance on interpreting text/JSON output and exit codes.