Skip to content

Commit e90afe2

Browse files
author
OpenAB Bot
committed
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
1 parent 7193372 commit e90afe2

3 files changed

Lines changed: 290 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
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+
## At a Glance
8+
9+
<!-- ASCII diagram showing the high-level flow or where this change fits in the system. Example:
10+
11+
┌──────────────┐ ┌───────┐ ┌───────────┐
12+
│ Discord User │────►│ openab│────►│ ACP Agent │
13+
└──────────────┘ └───┬───┘ └───────────┘
14+
│
15+
▼
16+
┌──────────────┐
17+
│ your change │
18+
└──────────────┘
19+
-->
20+
21+
```
22+
(your diagram here)
23+
```
24+
25+
## Prior Art & Industry Research
26+
27+
<!--
28+
Research how at least OpenClaw and Hermes Agent handle this problem.
29+
Include links to relevant docs, source code, or discussions.
30+
-->
31+
32+
**OpenClaw:**
33+
<!-- How does OpenClaw solve this? Link to relevant code/docs. -->
34+
35+
**Hermes Agent:**
36+
<!-- How does Hermes Agent solve this? Link to relevant code/docs. -->
37+
38+
**Other references (optional):**
39+
40+
## Proposed Solution
41+
42+
<!-- Describe your technical approach, architecture decisions, and key implementation details. -->
43+
44+
## Why this approach?
45+
46+
<!--
47+
Explain why you chose this approach over the alternatives found in your research.
48+
What are the tradeoffs? What are the known limitations?
49+
-->
50+
51+
## Alternatives Considered
52+
53+
<!-- List approaches you evaluated but did not choose, and why. -->
54+
55+
## Validation
56+
57+
<!-- How do you prove this works? Show, don't just tell. -->
58+
59+
- [ ] `cargo check` passes
60+
- [ ] `cargo test` passes (including new tests)
61+
- [ ] Manual testing — describe the steps you took and what you observed
62+
- [ ] Screenshots, logs, or terminal output demonstrating the feature working end-to-end

‎CONTRIBUTING.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Contributing to OpenAB
2+
3+
Thanks for your interest in contributing! This guide covers what we expect in pull requests.
4+
5+
## Pull Request Guidelines
6+
7+
Every PR must address the following in its description. The [PR template](/.github/pull_request_template.md) will prompt you for each section.
8+
9+
### 1. What problem does this solve?
10+
11+
Describe the pain point or requirement in plain language. Link the related issue.
12+
13+
### 2. Prior Art & Industry Research
14+
15+
Before proposing a solution, research how the industry handles the same problem. At minimum, investigate:
16+
17+
- **[OpenClaw](https://github.com/openclaw/openclaw)** — the largest open-source AI agent gateway
18+
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — Nous Research's self-hosted agent with multi-platform messaging
19+
20+
Include links to relevant source code, documentation, or discussions. If neither project addresses the problem, state that explicitly with evidence.
21+
22+
### 3. Proposed Solution & Why This Approach
23+
24+
Describe your technical approach, then explain why you chose it over the alternatives found in your research. Be explicit about:
25+
26+
- Tradeoffs you accepted
27+
- Known limitations
28+
- How this could evolve in the future
29+
30+
### 4. Alternatives Considered
31+
32+
List approaches you evaluated but did not choose, and explain why they were rejected.
33+
34+
### 5. Test Plan
35+
36+
- `cargo check` and `cargo test` must pass
37+
- Describe any manual testing performed
38+
- Add unit tests for new functionality
39+
40+
## Why We Require Prior Art Research
41+
42+
OpenAB is a young project. We want every design decision to be informed by what's already working in production elsewhere. This:
43+
44+
- Prevents reinventing the wheel
45+
- Surfaces better patterns we might not have considered
46+
- Documents the design space for future contributors
47+
- Makes reviews faster — reviewers don't have to do the research themselves
48+
49+
## Development Setup
50+
51+
```bash
52+
cargo build
53+
cargo test
54+
cargo check
55+
```
56+
57+
## Code Style
58+
59+
- Run `cargo fmt` before committing
60+
- Run `cargo clippy` and address warnings
61+
- Keep PRs focused — one feature or fix per PR

‎docs/rfcs/002-pr-guidelines.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# RFC 002: Pull Request Contribution Guidelines
2+
3+
| Field | Value |
4+
|-------|-------|
5+
| **RFC** | 002 |
6+
| **Title** | Pull Request Contribution Guidelines |
7+
| **Author** | @chaodu-agent |
8+
| **Status** | Draft |
9+
| **Created** | 2026-04-13 |
10+
11+
---
12+
13+
## Summary
14+
15+
Establish a standard PR template requiring contributors to research prior art (at minimum OpenClaw and Hermes Agent) before proposing solutions, and to document the problem, approach, tradeoffs, and alternatives in every PR description.
16+
17+
## Motivation
18+
19+
OpenAB is growing and accepting external contributions. Without a clear PR standard, we see PRs that:
20+
21+
- Jump straight to implementation without explaining the problem
22+
- Don't research how existing projects solve the same problem
23+
- Don't justify why a particular approach was chosen over alternatives
24+
- Make review harder because reviewers must do the research themselves
25+
26+
**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. This is the standard we want every PR to meet.
27+
28+
**What we want to avoid:** PRs that jump straight to implementation without documenting how existing projects solve the same problem — forcing reviewers to do the research themselves during review.
29+
30+
## Design
31+
32+
### Required PR Sections
33+
34+
Every PR must include these sections in its description:
35+
36+
| # | Section | Purpose |
37+
|---|---------|---------|
38+
| 1 | **What problem does this solve?** | Pain point or requirement in plain language. Link the related issue. |
39+
| 2 | **At a Glance** | ASCII diagram showing the high-level flow, architecture, or where the change fits in the system. |
40+
| 3 | **Prior Art & Industry Research** | How OpenClaw and Hermes Agent handle the same problem. Links to code/docs. |
41+
| 4 | **Proposed Solution** | Technical approach, architecture decisions, key implementation details. |
42+
| 5 | **Why This Approach** | Why this over the alternatives from research. Tradeoffs and limitations. |
43+
| 6 | **Alternatives Considered** | Approaches evaluated but not chosen, and why. |
44+
| 7 | **Validation** | How do you prove it works? Unit tests, integration tests, manual testing steps, screenshots, logs. |
45+
46+
### Mandatory Prior Art Research
47+
48+
Contributors must research at minimum these two projects:
49+
50+
| Project | Why it's mandatory |
51+
|---|---|
52+
| [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. |
53+
| [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. |
54+
55+
For each project, document:
56+
- How they solve the same problem (with links to source code or docs)
57+
- Key architectural decisions they made
58+
- What we can learn from their approach
59+
60+
If neither project addresses the problem, state that explicitly with evidence.
61+
62+
### Research Flow
63+
64+
```
65+
Contributor researches prior art
66+
│
67+
▼
68+
┌───────────────────────┐ ┌──────────────────────────────────┐
69+
│ Finds better pattern │────►│ Adopts it (we benefit) │
70+
└───────────┬───────────┘ └──────────────────────────────────┘
71+
│
72+
▼
73+
┌───────────────────────────┐ ┌──────────────────────────────────┐
74+
│ Finds different pattern │►│ Documents why we diverge │
75+
└───────────┬───────────────┘ │ (reviewers understand tradeoff) │
76+
│ └──────────────────────────────────┘
77+
▼
78+
┌───────────────────────────┐ ┌──────────────────────────────────┐
79+
│ Finds nothing relevant │►│ States so explicitly │
80+
└───────────────────────────┘ │ (saves reviewers from searching) │
81+
└──────────────────────────────────┘
82+
```
83+
84+
## Implementation
85+
86+
| Phase | Deliverable | Description |
87+
|-------|-------------|-------------|
88+
| **1** | `.github/pull_request_template.md` | Auto-populated PR form with all required sections |
89+
| **2** | `CONTRIBUTING.md` | Contributor guide explaining the guidelines and linking to this RFC |
90+
| **3** | Review process update | Reviewers check for prior art section completeness |
91+
92+
### PR Template
93+
94+
```markdown
95+
## What problem does this solve?
96+
97+
<!-- Describe the pain point in plain language. Link the related issue. -->
98+
99+
Closes #
100+
101+
## At a Glance
102+
103+
<!-- ASCII diagram showing the high-level flow or where this change fits in the system. Example:
104+
105+
┌──────────────┐ ┌───────┐ ┌───────────┐
106+
│ Discord User │────►│ openab│────►│ ACP Agent │
107+
└──────────────┘ └───┬───┘ └───────────┘
108+
│
109+
▼
110+
┌──────────────┐
111+
│ your change │
112+
└──────────────┘
113+
-->
114+
115+
```
116+
(your diagram here)
117+
```
118+
119+
## Prior Art & Industry Research
120+
121+
<!-- Research how at least OpenClaw and Hermes Agent handle this problem. -->
122+
123+
**OpenClaw:**
124+
<!-- How does OpenClaw solve this? Link to relevant code/docs. -->
125+
126+
**Hermes Agent:**
127+
<!-- How does Hermes Agent solve this? Link to relevant code/docs. -->
128+
129+
**Other references (optional):**
130+
131+
## Proposed Solution
132+
133+
<!-- Technical approach, architecture decisions, key implementation details. -->
134+
135+
## Why This Approach
136+
137+
<!-- Why this over the alternatives from your research? Tradeoffs? Limitations? -->
138+
139+
## Alternatives Considered
140+
141+
<!-- Approaches evaluated but not chosen, and why. -->
142+
143+
## Validation
144+
145+
<!-- How do you prove this works? Show, don't just tell. -->
146+
147+
- [ ] `cargo check` passes
148+
- [ ] `cargo test` passes (including new tests)
149+
- [ ] Manual testing — describe the steps you took and what you observed
150+
- [ ] Screenshots, logs, or terminal output demonstrating the feature working end-to-end
151+
```
152+
153+
## Open Questions
154+
155+
1. Should we enforce the prior art section via CI (e.g., a bot that checks for the section headers)?
156+
2. Should we maintain a living doc of "how OpenClaw/Hermes do X" to reduce per-PR research burden?
157+
3. Are there other mandatory reference projects beyond OpenClaw and Hermes?
158+
159+
---
160+
161+
## References
162+
163+
- Issue #224 / PR #225 — exemplary prior art research (STT: OpenClaw vs Hermes Agent comparison)
164+
- PR #300 — example of a PR that would benefit from this guideline
165+
- [OpenClaw Channel & Messaging Deep Dive](https://avasdream.com/blog/openclaw-channels-messaging-deep-dive)
166+
- [Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
167+
- RFC 001 — [Session Management](./001-session-management.md)

0 commit comments

Comments
 (0)