Skip to content

Commit ac6f83a

Browse files
Bueller87Bueller87
committed
docs: add PR template, guidance, and gitar rule for PR quality
- Add .github/pull_request_template.md with standard sections - Add .github/pull_request_guidance.md with cadence-samples-specific guidance (cmd/samples vs new_samples, Go/make test commands) - Add .gitar/rules/pr-description-quality.md for automated PR description checks Signed-off-by: “Kevin” <kevlar_ksb@yahoo.com>
1 parent df629fc commit ac6f83a

File tree

3 files changed

+154
-0
lines changed

3 files changed

+154
-0
lines changed

‎.gitar/rules/pr-description-quality.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: PR Description Quality Standards
3+
description: Ensures PR descriptions meet quality criteria for the cadence-samples (Go) repo using guidance from the PR template and .github/pull_request_guidance.md
4+
when: PR description is created or updated
5+
actions: Read PR template and guidance, then report requirement status
6+
---
7+
8+
# PR Description Quality Standards
9+
10+
When evaluating a pull request description:
11+
12+
1. **Read the PR template guidance** at `.github/pull_request_guidance.md` to understand the expected guidance for each section
13+
2. Apply that guidance to evaluate the current PR description
14+
3. Provide recommendations for how to improve the description.
15+
16+
## Core Principle: Why Not How
17+
18+
From https://cbea.ms/git-commit/#why-not-how:
19+
- **"A diff shows WHAT changed, but only the description can explain WHY"**
20+
- Focus on: the problem being solved, the reasoning behind the solution, context
21+
- The code itself documents HOW - the PR description documents WHY
22+
23+
## Evaluation Criteria
24+
25+
### Required Sections (must exist with substantive content per PR template guidance)
26+
27+
1. **Which sample(s) or area?** (optional but recommended)
28+
- One line listing area(s) touched. This repo has two sample trees: **cmd/samples** (legacy; make + ./bin/…) and **new_samples** (per-folder; go run .). Identify which tree and area(s) are touched.
29+
- **cmd/samples:** e.g. cmd/samples/recipes/helloworld, cmd/samples/recipes/branch, cmd/samples/recipes/query, cmd/samples/batch, cmd/samples/cron, cmd/samples/expense, cmd/samples/fileprocessing, cmd/samples/dsl, cmd/samples/pso, cmd/samples/recovery, cmd/samples/recipes/cancelactivity, etc.
30+
- **new_samples:** hello_world, activities, query, signal, operations, client_tls, template.
31+
- **Other:** README, build, config, Makefile, common.
32+
- Helps reviewers route; skip flagging if area is obvious from paths
33+
34+
2. **What changed?**
35+
- 1-2 line summary of WHAT changed technically
36+
- Focus on key modification, not implementation details
37+
- Link to GitHub issue encouraged for non-trivial changes; optional for trivial doc/sample tweaks
38+
- Template has good/bad examples
39+
40+
3. **Why?**
41+
- Context and motivation (why not how)
42+
- Enough rationale for reviewers to understand the goal (e.g. improving clarity, fixing compatibility, aligning with docs)
43+
- Must explain WHY this approach was chosen
44+
45+
4. **How did you test it?**
46+
- Concrete, copyable commands with exact invocations
47+
- GOOD: `make`, `go test ./...`, `go test ./cmd/samples/recipes/helloworld/`, `cd new_samples/hello_world && go run .`, and Cadence CLI commands as in sample READMEs
48+
- BAD: "Tested locally" or "See tests"
49+
- Expect Go/make and/or sample execution commands; no canary or integration server setup required
50+
51+
5. **Potential risks**
52+
- Often N/A for sample-only or doc-only changes
53+
- Call out when relevant: dependency upgrades, behavior changes for someone copying the sample, build/config changes
54+
- Don't require lengthy text when N/A is appropriate
55+
56+
6. **Release notes**
57+
- Optional for this repo. Use when change is user-facing (e.g. new sample, notable README change)
58+
- Can be N/A for internal refactors or tiny fixes
59+
- Don't require lengthy text when N/A is appropriate
60+
61+
7. **Documentation Changes**
62+
- Often relevant when adding or changing samples (main README, cmd/samples READMEs, new_samples READMEs including generator-generated, links to cadence or cadence-docs)
63+
- Only mark N/A if certain no docs are affected
64+
65+
### Quality Checks
66+
67+
- **Skip obvious things** - Don't flag items clear from folder structure (e.g. area from paths)
68+
- **Skip trivial refactors** - Minor formatting/style changes don't need deep rationale
69+
- **Don't check automated items** - CI, linting are automated
70+
71+
## FORBIDDEN - Never Include
72+
73+
- "Issues Found", "Testing Evidence Quality", "Documentation Reasoning", "Summary" sections
74+
- "Note:" paragraphs or explanatory text outside recommendations
75+
- Grouping recommendations by type
76+
77+
## Section Names (Use EXACT Brackets)
78+
79+
- **[Which sample(s) or area?]**
80+
- **[What changed?]**
81+
- **[Why?]**
82+
- **[How did you test it?]**
83+
- **[Potential risks]**
84+
- **[Release notes]**
85+
- **[Documentation Changes]**

‎.github/pull_request_guidance.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
<!-- List the area(s) touched so reviewers know where to look.
2+
This repo has two sample trees: legacy samples under cmd/samples (built with make, run via ./bin/<name>) and newer samples under new_samples (per-folder, run with go run .). Naming the area helps reviewers.
3+
Examples: cmd/samples/recipes/helloworld, cmd/samples/batch, cmd/samples/expense, new_samples/hello_world, new_samples/query, new_samples/operations, README, build, config, Makefile -->
4+
**Which sample(s) or area?**
5+
6+
7+
<!-- 1-2 line summary of WHAT changed technically.
8+
- Link to a GitHub issue when applicable (encouraged for larger changes; optional for trivial doc/sample tweaks)
9+
- Good: "Added CancelWorkflow sample in new_samples/operations" or "Updated README run instructions for Go 1.21"
10+
- Bad: "updated code" or "fixed stuff" -->
11+
**What changed?**
12+
13+
14+
<!-- Provide context and motivation (see https://cbea.ms/git-commit/#why-not-how). Focus on WHY, not how.
15+
- Lighter than core Cadence repo: e.g. "improving clarity for new users," "fixing sample broken on Go 1.21," "aligning with cadence-docs"
16+
- Still give enough rationale for reviewers to understand the goal
17+
- Good: "HelloWorld didn't show retry behavior; this sample demonstrates RetryOptions so users can copy-paste a working example."
18+
- Bad: "Improves samples" -->
19+
**Why?**
20+
21+
22+
<!-- Include concrete, copy-paste commands so another maintainer can reproduce your test steps.
23+
- Prefer: make, go test ./... (or a targeted test, e.g. go test ./cmd/samples/recipes/helloworld/)
24+
- For cmd/samples: make then e.g. ./bin/helloworld -m worker and ./bin/helloworld -m trigger
25+
- For new_samples: cd new_samples/<sample> && go run . and Cadence CLI commands as in the sample README
26+
- Good: Full commands reviewers can copy-paste to verify
27+
- Bad: "Tested locally" or "See tests" -->
28+
**How did you test it?**
29+
30+
31+
<!-- Often N/A for sample-only or doc-only changes. Call out when relevant:
32+
- Dependency upgrades (e.g. cadence-client version)
33+
- Behavior changes that could affect someone copying the sample
34+
- Build or config changes
35+
- If truly N/A, you can mark it as such -->
36+
**Potential risks**
37+
38+
39+
<!-- Optional for this repo. Use when the change is user-facing (e.g. new sample, notable README change).
40+
- Can be N/A for internal refactors, tiny fixes, or incremental work -->
41+
**Release notes**
42+
43+
44+
<!-- Did you update the main README, a cmd/samples README, or a new_samples README (including generator-generated READMEs)?
45+
- Any links to cadence or cadence-docs that need updating?
46+
- Only mark N/A if you're certain no docs are affected -->
47+
**Documentation Changes**
48+

‎.github/pull_request_template.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<!-- If you are new to contributing or want a refresher, please read .github/pull_request_guidance.md -->
2+
**Which sample(s) or area?**
3+
4+
5+
**What changed?**
6+
7+
8+
**Why?**
9+
10+
11+
**How did you test it?**
12+
13+
14+
**Potential risks**
15+
16+
17+
**Release notes**
18+
19+
20+
**Documentation Changes**
21+

0 commit comments

Comments
 (0)