Skip to content

Commit e492d66

Browse files
masami-agentopenab-botchaodufashichaodu-agent
authored
docs: implement tiered PR contribution guidelines (#679)
* RFC 002: PR contribution guidelines with mandatory prior art research Add RFC, PR template, and CONTRIBUTING.md requiring contributors to research OpenClaw and Hermes Agent before proposing solutions. - docs/rfcs/002-pr-guidelines.md — full RFC (follows RFC 001 format) - .github/pull_request_template.md — auto-populated PR form - CONTRIBUTING.md — contributor guide linking to RFC * feat: add Discord Discussion URL field to PR template, CONTRIBUTING.md, and RFC * docs: reformat RFC 002 as ADR under docs/adr/ Move PR contribution guidelines from docs/rfcs/ to docs/adr/ format, matching the existing ADR structure (line-adapter, custom-gateway). * docs: implement tiered PR contribution guidelines Rework PR #302 to address review feedback from @shaun-agent and @masami-agent: - Prior art research: required for architectural/runtime changes, N/A for docs/chore/CI - Validation section: multi-surface (Rust, Helm, CI, docs) instead of Rust-only - Discord Discussion URL: strongly recommended instead of auto-close policy - CONTRIBUTING.md: add link to ADR as specified in implementation table - ADR: update to reflect tiered policy (Option 3) as adopted approach - Fix trailing whitespace in PR template * docs: align CONTRIBUTING.md sections with ADR, update status to Accepted - CONTRIBUTING.md now has all 8 sections (0-7) matching the ADR table - Added missing sections: At a Glance (#2), split Proposed Solution (#4) and Why This Approach (#5) into separate sections - ADR status updated from Proposed to Accepted --------- Co-authored-by: OpenAB Bot <openab-bot@users.noreply.github.com> Co-authored-by: chaodufashi <chaodu-agent@openab.dev> Co-authored-by: chaodu-agent <chaodu-agent@users.noreply.github.com> Co-authored-by: Masami <masami-agent@users.noreply.github.com>
1 parent f634cd9 commit e492d66

3 files changed

Lines changed: 278 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
## What problem does this solve?
2+
3+
<!-- Describe the pain point or requirement in plain language. Link the related issue if one exists. -->
4+
5+
Closes #
6+
7+
Discord Discussion URL: <!-- Strongly recommended. Link the Discord thread where this was discussed. -->
8+
9+
## At a Glance
10+
11+
<!-- ASCII diagram showing the high-level flow or where this change fits in the system. For docs-only or trivial changes, write "N/A". -->
12+
13+
```
14+
(your diagram here)
15+
```
16+
17+
## Prior Art & Industry Research
18+
19+
<!--
20+
Required for architectural, runtime, agent, scheduling, delivery, or persistence changes.
21+
For docs-only, chore, CI, release, or trivial bug fixes, write "Not applicable — [reason]".
22+
23+
Research how at least OpenClaw and Hermes Agent handle this problem.
24+
Include links to relevant docs, source code, or discussions.
25+
-->
26+
27+
**OpenClaw:**
28+
<!-- How does OpenClaw solve this? Link to relevant code/docs. -->
29+
30+
**Hermes Agent:**
31+
<!-- How does Hermes Agent solve this? Link to relevant code/docs. -->
32+
33+
**Other references (optional):**
34+
35+
## Proposed Solution
36+
37+
<!-- Describe your technical approach, architecture decisions, and key implementation details. -->
38+
39+
## Why this approach?
40+
41+
<!--
42+
Explain why you chose this approach over the alternatives found in your research.
43+
What are the tradeoffs? What are the known limitations?
44+
-->
45+
46+
## Alternatives Considered
47+
48+
<!-- List approaches you evaluated but did not choose, and why. -->
49+
50+
## Validation
51+
52+
<!--
53+
Show that your change works. Pick the checks relevant to your PR type:
54+
55+
Rust changes:
56+
- [ ] `cargo check` passes
57+
- [ ] `cargo test` passes (including new tests)
58+
- [ ] `cargo clippy` clean
59+
60+
Helm chart changes:
61+
- [ ] `helm lint charts/openab` passes
62+
- [ ] `helm template` renders correctly
63+
64+
CI/workflow changes:
65+
- [ ] Workflow syntax is valid
66+
- [ ] Tested with act or dry-run where possible
67+
68+
Docs-only changes:
69+
- [ ] Links are valid
70+
- [ ] Renders correctly in GitHub preview
71+
72+
All PRs:
73+
- [ ] Manual testing — describe the steps you took and what you observed
74+
-->

‎CONTRIBUTING.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Contributing to OpenAB
2+
3+
Thanks for your interest in contributing! This guide covers what we expect in pull requests.
4+
5+
For the full rationale behind these guidelines, see the [PR Contribution Guidelines ADR](/docs/adr/pr-contribution-guidelines.md).
6+
7+
## Pull Request Guidelines
8+
9+
Every PR must address the following in its description. The [PR template](/.github/pull_request_template.md) will prompt you for each section.
10+
11+
### 0. Discord Discussion URL
12+
13+
We strongly recommend including a Discord Discussion URL in the PR body (e.g. `https://discord.com/channels/...`). Discussing your idea in Discord before opening a PR helps align on direction and avoids wasted effort. If no Discord discussion exists, explain the context directly in the PR description.
14+
15+
### 1. What problem does this solve?
16+
17+
Describe the pain point or requirement in plain language. Link the related issue.
18+
19+
### 2. At a Glance
20+
21+
Provide an ASCII diagram showing the high-level flow or where your change fits in the system. For docs-only or trivial changes, write "N/A".
22+
23+
### 3. Prior Art & Industry Research
24+
25+
**Required for architectural, runtime, agent, scheduling, delivery, or persistence changes.** For docs-only, chore, CI, release, or trivial bug fixes, write "Not applicable" with a brief reason.
26+
27+
When prior art research is required, investigate at minimum:
28+
29+
- **[OpenClaw](https://github.com/openclaw/openclaw)** — the largest open-source AI agent gateway
30+
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — Nous Research's self-hosted agent with multi-platform messaging
31+
32+
Include links to relevant source code, documentation, or discussions. If neither project addresses the problem, state that explicitly with evidence.
33+
34+
### 4. Proposed Solution
35+
36+
Describe your technical approach, architecture decisions, and key implementation details.
37+
38+
### 5. Why This Approach
39+
40+
Explain why you chose this approach over the alternatives found in your research. Be explicit about:
41+
42+
- Tradeoffs you accepted
43+
- Known limitations
44+
- How this could evolve in the future
45+
46+
### 6. Alternatives Considered
47+
48+
List approaches you evaluated but did not choose, and explain why they were rejected.
49+
50+
### 7. Validation
51+
52+
Pick the checks relevant to your PR type:
53+
54+
- **Rust changes:** `cargo check`, `cargo test`, `cargo clippy`
55+
- **Helm chart changes:** `helm lint`, `helm template`
56+
- **CI/workflow changes:** workflow syntax validation, dry-run where possible
57+
- **Docs-only changes:** links are valid, renders correctly in GitHub preview
58+
59+
Describe any manual testing performed and add unit tests for new functionality.
60+
61+
## Why We Require Prior Art Research
62+
63+
OpenAB is a young project. We want every design decision to be informed by what's already working in production elsewhere. This:
64+
65+
- Prevents reinventing the wheel
66+
- Surfaces better patterns we might not have considered
67+
- Documents the design space for future contributors
68+
- Makes reviews faster — reviewers don't have to do the research themselves
69+
70+
## Development Setup
71+
72+
```bash
73+
cargo build
74+
cargo test
75+
cargo check
76+
```
77+
78+
## Code Style
79+
80+
- Run `cargo fmt` before committing
81+
- Run `cargo clippy` and address warnings
82+
- Keep PRs focused — one feature or fix per PR

‎docs/adr/pr-contribution-guidelines.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# ADR: PR Contribution Guidelines
2+
3+
- **Status:** Accepted
4+
- **Date:** 2026-04-13
5+
- **Author:** @chaodu-agent
6+
7+
---
8+
9+
## 1. Context & Problem Statement
10+
11+
OpenAB is growing and accepting external contributions. Without a clear PR standard, we see PRs that:
12+
13+
- Jump straight to implementation without explaining the problem
14+
- Don't research how existing projects solve the same problem
15+
- Don't justify why a particular approach was chosen over alternatives
16+
- Make review harder because reviewers must do the research themselves
17+
18+
This front-loads research cost onto the contributor (who understands the problem best) rather than distributing it across reviewers.
19+
20+
**Good example:** Issue #224 / PR #225 (voice message STT) included a thorough prior art investigation — comparing OpenClaw's `audio-transcription-runner.ts` preflight pipeline with Hermes Agent's `transcription_tools.py` local-first approach, producing a clear comparison table, and explaining why OpenAB chose a simpler OpenAI-compatible endpoint design.
21+
22+
## 2. Decision
23+
24+
Establish a standard PR template and tiered contribution guidelines. All PRs document the problem, approach, tradeoffs, and alternatives. Architectural and runtime changes additionally require prior art research (at minimum OpenClaw and Hermes Agent). Docs-only, chore, CI, release, and trivial bug fixes use a lighter process.
25+
26+
### Required PR Sections
27+
28+
Every PR must include these sections in its description:
29+
30+
| # | Section | Purpose |
31+
|---|---------|---------|
32+
| 0 | **Discord Discussion URL** | Strongly recommended. Link to the prior Discord discussion. If none exists, explain context in the PR description. |
33+
| 1 | **What problem does this solve?** | Pain point or requirement in plain language. Link the related issue. |
34+
| 2 | **At a Glance** | ASCII diagram showing the high-level flow, architecture, or where the change fits in the system. "N/A" for docs-only or trivial changes. |
35+
| 3 | **Prior Art & Industry Research** | Required for architectural/runtime changes. "Not applicable" with reason for docs/chore/CI/release/trivial fixes. |
36+
| 4 | **Proposed Solution** | Technical approach, architecture decisions, key implementation details. |
37+
| 5 | **Why This Approach** | Why this over the alternatives from research. Tradeoffs and limitations. |
38+
| 6 | **Alternatives Considered** | Approaches evaluated but not chosen, and why. |
39+
| 7 | **Validation** | Relevant checks for the PR type: Rust, Helm, CI, or docs validation as applicable. |
40+
41+
### Tiered Prior Art Research
42+
43+
Prior art research is **required** for PRs that touch architectural, runtime, agent, scheduling, delivery, or persistence concerns. Contributors must research at minimum these two projects:
44+
45+
| Project | Why it's a reference |
46+
|---|---|
47+
| [OpenClaw](https://github.com/openclaw/openclaw) | Largest open-source AI agent gateway. Plugin architecture across 7+ messaging platforms. Mature patterns for media, security, session management. |
48+
| [Hermes Agent](https://github.com/NousResearch/hermes-agent) | Nous Research's self-hosted agent. Gateway architecture across 17+ platforms. Strong prior art on messaging, tool integration, and service management. |
49+
50+
For each project, document:
51+
- How they solve the same problem (with links to source code or docs)
52+
- Key architectural decisions they made
53+
- What we can learn from their approach
54+
55+
If neither project addresses the problem, state that explicitly with evidence.
56+
57+
For **docs-only, chore, CI, release, or trivial bug fixes**, write "Not applicable — [reason]" in the prior art section.
58+
59+
### Research Flow
60+
61+
```text
62+
Contributor researches prior art
63+
│
64+
▼
65+
┌───────────────────────┐ ┌──────────────────────────────────┐
66+
│ Finds better pattern │────►│ Adopts it (we benefit) │
67+
└───────────┬───────────┘ └──────────────────────────────────┘
68+
│
69+
▼
70+
┌───────────────────────────┐ ┌──────────────────────────────────┐
71+
│ Finds different pattern │►│ Documents why we diverge │
72+
└───────────┬───────────────┘ │ (reviewers understand tradeoff) │
73+
│ └──────────────────────────────────┘
74+
▼
75+
┌───────────────────────────┐ ┌──────────────────────────────────┐
76+
│ Finds nothing relevant │►│ States so explicitly │
77+
└───────────────────────────┘ │ (saves reviewers from searching) │
78+
└──────────────────────────────────┘
79+
```
80+
81+
## 3. Implementation
82+
83+
| Phase | Deliverable | Description |
84+
|-------|-------------|-------------|
85+
| **1** | `.github/pull_request_template.md` | Auto-populated PR form with all required sections |
86+
| **2** | `CONTRIBUTING.md` | Contributor guide explaining the tiered guidelines and linking to this ADR |
87+
| **3** | Review process update | Reviewers check for prior art section completeness |
88+
89+
## 4. Alternatives Considered
90+
91+
### Option 1: No formal template — rely on reviewer feedback
92+
93+
- Pros: zero contributor friction
94+
- Cons: inconsistent quality, reviewers repeat the same feedback, research burden falls on reviewers
95+
96+
### Option 2: Strict mandatory template everywhere
97+
98+
- Pros: uniform quality across all PRs
99+
- Cons: excessive overhead for trivial/docs/small fixes; may discourage contributions
100+
101+
### Option 3: Tiered policy by PR type (adopted)
102+
103+
- Pros: full prior-art analysis for architectural changes, lighter structure for minor PRs
104+
- Cons: requires defining the boundary between "minor" and "architectural"
105+
106+
## 5. Open Questions
107+
108+
1. Should we enforce the prior art section via CI (e.g., a bot that checks for the section headers)?
109+
2. Should we maintain a living doc of "how OpenClaw/Hermes do X" to reduce per-PR research burden?
110+
3. Are there other mandatory reference projects beyond OpenClaw and Hermes?
111+
112+
## Consequences
113+
114+
- **Positive:** Higher-quality PRs, faster reviews, architectural consistency, less reinventing the wheel
115+
- **Negative:** Higher upfront cost for contributors on architectural PRs; may slow down first-time contributions
116+
- **Mitigation:** Clear examples (PR #225), PR template auto-populates sections, tiered policy keeps docs/chore/CI contributions lightweight
117+
118+
## References
119+
120+
- Issue #224 / PR #225 — exemplary prior art research (STT: OpenClaw vs Hermes Agent comparison)
121+
- [OpenClaw Channel & Messaging Deep Dive](https://avasdream.com/blog/openclaw-channels-messaging-deep-dive)
122+
- [Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)

0 commit comments

Comments
 (0)