Skip to content

Commit 33cbd54

Browse files
justrachjustrach
committed
Add Rach's agentic contribution template
1 parent 0fdb37e commit 33cbd54

2 files changed

Lines changed: 184 additions & 66 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 67 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,75 @@
1+
## Rach's Agentic Contribution Template
2+
3+
Maintainer process template by [@rachpradhan](https://x.com/rachpradhan).
4+
5+
## Linked Issue
6+
7+
Closes #
8+
9+
If this PR is not tied to an existing issue, open one first.
10+
111
## Summary
212

3-
<!-- What does this PR do? Link the issue it closes if applicable: "Closes #N" -->
13+
- what changed
14+
- why it changed
15+
- what is intentionally not in scope
16+
17+
## Scope
18+
19+
- subsystems touched:
20+
- generated files changed: yes/no
21+
- lockfile changed: yes/no
22+
- benchmark/docs-only/runtime change:
23+
- changed lines count:
24+
25+
## Rebase Status
26+
27+
- [ ] Rebasing onto current `main` completed before requesting review
28+
29+
## Tests Run
30+
31+
```bash
32+
# paste exact commands here
33+
```
34+
35+
## Red-To-Green Evidence
36+
37+
### Failing Before
38+
39+
```bash
40+
# paste the exact failing test or repro command here
41+
```
42+
43+
### Passing After
44+
45+
```bash
46+
# paste the exact passing rerun here
47+
```
48+
49+
### Nearby Non-Regression Checks
450

5-
## Type of change
51+
```bash
52+
# paste the closest neighboring tests / guards you ran here
53+
```
654

7-
- [ ] Bug fix
8-
- [ ] New feature
9-
- [ ] Refactor (no behaviour change)
10-
- [ ] Documentation
55+
## Benchmarks
1156

12-
## Test plan
57+
If this PR changes benchmark code or benchmark claims, fill this out:
1358

14-
- [ ] `zig fmt` passes (enforced by pre-commit hook)
15-
- [ ] `zig build` compiles without errors
16-
- [ ] `zig build test` passes
17-
- [ ] Manually tested: <!-- describe what you ran -->
59+
- layer measured:
60+
- caches disabled or enabled:
61+
- warmup policy:
62+
- number of runs:
63+
- local or CI:
64+
- environment:
1865

19-
## Breaking changes
66+
## Checklist
2067

21-
<!-- List any breaking API changes, or write "None". -->
68+
- [ ] PR is matched to an issue
69+
- [ ] PR scope is narrow and reviewable
70+
- [ ] PR is under 500 changed lines, or I justified why it cannot be split
71+
- [ ] I showed the failing test or repro before the fix
72+
- [ ] I showed the same test or repro passing after the fix
73+
- [ ] I ran nearby non-regression checks, not just the one happy-path test
74+
- [ ] No generated `.zig-cache`, `zig-out`, dylibs, or other build artifacts are committed
75+
- [ ] No unrelated dependency or lockfile churn is included

‎CONTRIBUTING.md‎

Lines changed: 117 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,139 @@
1-
# Contributing to merjs
1+
# Rach's Agentic Contribution Template
22

3-
Thanks for your interest. merjs is experimental — expect sharp edges and API churn.
3+
Maintainer process template by [@rachpradhan](https://x.com/rachpradhan).
44

5-
## Prerequisites
5+
This repo moves quickly. Small, current, issue-linked PRs are much easier to review and much less likely to regress behavior.
66

7-
- [Zig 0.15.x](https://ziglang.org/download/) — check with `zig version`
8-
- macOS or Linux (Windows is untested)
7+
## Ground Rules
98

10-
## Local setup
9+
1. Every PR must be tied to an issue.
10+
2. Rebase onto current `main` before requesting final review.
11+
3. Keep PRs tightly scoped.
12+
4. Do not commit generated artifacts.
13+
5. Do not mix unrelated lockfile churn, scaffolding, or benchmark churn into a focused fix.
14+
6. Keep each PR under **500 changed lines** by default.
1115

12-
```bash
13-
git clone https://github.com/justrach/merjs.git
14-
cd merjs
15-
git config core.hooksPath .githooks # enable pre-commit (fmt+build) and pre-push (test)
16-
```
16+
If a branch goes stale, close it and open a smaller replacement instead of piling more changes onto the old PR.
1717

18-
## One-command dev start
18+
## PR Requirements
1919

20-
```bash
21-
zig build codegen # generate src/generated/routes.zig from app/
22-
zig build serve # start dev server on :3000 with hot reload
23-
```
20+
Every PR description should include:
21+
22+
- linked issue number
23+
- summary of the exact change
24+
- files or subsystems touched
25+
- tests run
26+
- failing test, xfail, or exact repro that demonstrated the problem before the fix
27+
- passing rerun of that same test or repro after the fix
28+
- nearby non-regression checks proving the change did not just move the bug
29+
- whether the branch was rebased onto current `main`
30+
- whether any generated files, lockfiles, or benchmarks changed
31+
32+
If a PR does not map cleanly to an issue, open the issue first.
33+
34+
## Red-To-Green Rule
35+
36+
For bug fixes, compatibility fixes, runtime fixes, and perf regressions:
37+
38+
1. show the failing test, xfail, or exact repro first
39+
2. make the code change
40+
3. rerun the same test or repro and show it passing
41+
4. run the closest neighboring tests to prove the fix did not just move the bug
42+
43+
If there is no failing test yet, write one first unless the failure is impossible to encode cleanly.
44+
45+
## Scope Rules
46+
47+
Good PR scope:
48+
49+
- one bug fix
50+
- one benchmark methodology fix
51+
- one small perf change
52+
- one docs-only clarification
53+
54+
Bad PR scope:
55+
56+
- runtime change + unrelated refactor
57+
- perf tweak + dependency upgrade
58+
- feature work + generated build output
59+
- benchmark change + docs rewrite + lockfile churn
2460

25-
Or via the `mer` CLI (built from `cli.zig`):
61+
If a reviewer cannot explain the PR in one sentence, it is probably too large.
62+
63+
## Rebase Policy
64+
65+
Before requesting review on any non-trivial PR:
2666

2767
```bash
28-
zig build cli # produces zig-out/bin/mer
29-
./zig-out/bin/mer dev # codegen + serve in one step
68+
git fetch origin
69+
git rebase origin/main
3070
```
3171

32-
## Build targets
72+
If rebasing reveals unrelated conflicts, split the PR.
73+
74+
## Generated Files
75+
76+
Do not commit generated or local-build artifacts, including:
77+
78+
- `.zig-cache/`
79+
- `zig-out/`
80+
- `.dylib`, `.so`, `.o`
81+
- local benchmark artifacts/logs unless the PR is explicitly about publishing benchmark evidence
82+
83+
If a file is generated during local builds, add or update `.gitignore` instead of committing it.
84+
85+
## Lockfiles And Dependencies
86+
87+
Do not update lockfiles unless the PR actually changes dependencies.
88+
89+
If you touch dependency metadata:
90+
91+
- explain why
92+
- keep that change isolated
93+
- mention it clearly in the PR summary
94+
95+
## Tests
96+
97+
Run the narrowest relevant tests for the code you changed.
98+
99+
For fixes, do not just say “tests passed”.
100+
101+
Show:
102+
103+
- the failing command before the fix
104+
- the passing command after the fix
105+
- at least one neighboring or regression-guard command
33106

34-
| Command | What it does |
35-
|---|---|
36-
| `zig build` | Compile the framework binary |
37-
| `zig build serve` | Dev server on :3000, hot reload |
38-
| `zig build codegen` | Regenerate `src/generated/routes.zig` |
39-
| `zig build worker` | Compile `worker/merjs.wasm` for Cloudflare Workers |
40-
| `zig build desktop` | Native macOS `.app` bundle (macOS only, experimental) |
41-
| `zig build test` | Run unit tests |
42-
| `zig build test-auth` | Run `packages/merjs-auth` tests |
43-
| `zig build css` | Recompile Tailwind → `public/styles.css` |
107+
## Benchmark PRs
44108

45-
## Before submitting a PR
109+
Benchmark-related PRs must say:
46110

47-
1. `zig fmt src/ app/ api/ examples/ *.zig` — formatter is enforced by pre-commit hook
48-
2. `zig build` — must compile without errors
49-
3. `zig build test` — must pass
50-
4. Open an issue first for anything non-trivial so we can align on approach
111+
- what layer is being measured
112+
- whether caches are on or off
113+
- whether numbers are cold-start or warmed steady-state
114+
- number of runs
115+
- whether values are single-run or median
116+
- exact machine or CI environment
51117

52-
## Branch naming
118+
Do not publish cached results as uncached performance.
53119

54-
- `feat/<name>` — new feature
55-
- `fix/<name>` — bug fix
56-
- `docs/<name>` — documentation only
57-
- `refactor/<name>` — no behaviour change
120+
## Review Expectations
58121

59-
## Repo layout
122+
Reviewers will push back on:
60123

61-
See [docs/architecture.md](docs/architecture.md) for a full breakdown. The short version:
124+
- stale branches
125+
- unrelated file churn
126+
- generated artifacts
127+
- oversized PRs
128+
- missing issue links
129+
- claims that do not match the changed code
62130

63-
- `src/` — framework runtime (server, router, SSR, HTML builder, watcher)
64-
- `app/`, `api/`, `public/` — the merjs website / demo app (not the framework itself)
65-
- `examples/` — standalone demo apps (kanban, desktop, singapore-data-dashboard)
66-
- `packages/` — optional packages (`merjs-auth`)
67-
- `cli.zig` — `mer` CLI entry point
68-
- `wasm/` — client-side WASM modules
131+
That is process, not hostility.
69132

70-
## Reporting bugs
133+
The easiest way to get a fast review is:
71134

72-
Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md). Please include:
73-
- `zig version` output
74-
- OS + arch
75-
- Minimal reproduction steps
135+
1. open an issue
136+
2. make a small branch
137+
3. rebase onto `main`
138+
4. keep the diff narrow
139+
5. include exact tests and rationale

0 commit comments

Comments
 (0)