Skip to content

Commit 7ffcd81

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 7ffcd81

3 files changed

Lines changed: 240 additions & 0 deletions

File tree

‎.github/pull_request_template.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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+
## Prior Art & Industry Research
8+
9+
<!--
10+
Research how at least OpenClaw and Hermes Agent handle this problem.
11+
Include links to relevant docs, source code, or discussions.
12+
-->
13+
14+
**OpenClaw:**
15+
<!-- How does OpenClaw solve this? Link to relevant code/docs. -->
16+
17+
**Hermes Agent:**
18+
<!-- How does Hermes Agent solve this? Link to relevant code/docs. -->
19+
20+
**Other references (optional):**
21+
22+
## Proposed Solution
23+
24+
<!-- Describe your technical approach, architecture decisions, and key implementation details. -->
25+
26+
## Why this approach?
27+
28+
<!--
29+
Explain why you chose this approach over the alternatives found in your research.
30+
What are the tradeoffs? What are the known limitations?
31+
-->
32+
33+
## Alternatives Considered
34+
35+
<!-- List approaches you evaluated but did not choose, and why. -->
36+
37+
## Test Plan
38+
39+
<!-- How did you verify this works? Include test commands, coverage, and manual testing steps. -->
40+
41+
- [ ] `cargo check` passes
42+
- [ ] `cargo test` passes
43+
- [ ] Manual testing done (describe below)

‎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: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# RFC 002: Pull Request Contribution Guidelines
2+
3+
| Field | Value |
4+
|-------|-------|
5+
| **RFC** | 002 |
6+
| **Title** | Pull Request Contribution Guidelines |
7+
| **Author** | @pahud |
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+
Example: PR #300 (outbound attachments) proposed a regex-from-response approach without documenting how OpenClaw uses tool-based `sendAttachment` actions or how Hermes Agent handles media at the gateway adapter layer. Reviewers had to do this research during review.
27+
28+
## Design
29+
30+
### Required PR Sections
31+
32+
Every PR must include these sections in its description:
33+
34+
| # | Section | Purpose |
35+
|---|---------|---------|
36+
| 1 | **What problem does this solve?** | Pain point or requirement in plain language. Link the related issue. |
37+
| 2 | **Prior Art & Industry Research** | How OpenClaw and Hermes Agent handle the same problem. Links to code/docs. |
38+
| 3 | **Proposed Solution** | Technical approach, architecture decisions, key implementation details. |
39+
| 4 | **Why This Approach** | Why this over the alternatives from research. Tradeoffs and limitations. |
40+
| 5 | **Alternatives Considered** | Approaches evaluated but not chosen, and why. |
41+
| 6 | **Test Plan** | `cargo check`, `cargo test`, manual testing, new tests added. |
42+
43+
### Mandatory Prior Art Research
44+
45+
Contributors must research at minimum these two projects:
46+
47+
| Project | Why it's mandatory |
48+
|---|---|
49+
| [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. |
50+
| [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. |
51+
52+
For each project, document:
53+
- How they solve the same problem (with links to source code or docs)
54+
- Key architectural decisions they made
55+
- What we can learn from their approach
56+
57+
If neither project addresses the problem, state that explicitly with evidence.
58+
59+
### Research Flow
60+
61+
```
62+
Contributor researches prior art
63+
│
64+
▼
65+
Finds better pattern ──► Adopts it (we benefit)
66+
│
67+
▼
68+
Finds different pattern ──► Documents why we diverge
69+
│ (reviewers understand the tradeoff)
70+
▼
71+
Finds nothing relevant ──► States so explicitly
72+
(saves reviewers from searching)
73+
```
74+
75+
## Implementation
76+
77+
| Phase | Deliverable | Description |
78+
|-------|-------------|-------------|
79+
| **1** | `.github/pull_request_template.md` | Auto-populated PR form with all required sections |
80+
| **2** | `CONTRIBUTING.md` | Contributor guide explaining the guidelines and linking to this RFC |
81+
| **3** | Review process update | Reviewers check for prior art section completeness |
82+
83+
### PR Template
84+
85+
```markdown
86+
## What problem does this solve?
87+
88+
<!-- Describe the pain point in plain language. Link the related issue. -->
89+
90+
Closes #
91+
92+
## Prior Art & Industry Research
93+
94+
<!-- Research how at least OpenClaw and Hermes Agent handle this problem. -->
95+
96+
**OpenClaw:**
97+
<!-- How does OpenClaw solve this? Link to relevant code/docs. -->
98+
99+
**Hermes Agent:**
100+
<!-- How does Hermes Agent solve this? Link to relevant code/docs. -->
101+
102+
**Other references (optional):**
103+
104+
## Proposed Solution
105+
106+
<!-- Technical approach, architecture decisions, key implementation details. -->
107+
108+
## Why This Approach
109+
110+
<!-- Why this over the alternatives from your research? Tradeoffs? Limitations? -->
111+
112+
## Alternatives Considered
113+
114+
<!-- Approaches evaluated but not chosen, and why. -->
115+
116+
## Test Plan
117+
118+
- [ ] `cargo check` passes
119+
- [ ] `cargo test` passes
120+
- [ ] Manual testing (describe below)
121+
```
122+
123+
## Open Questions
124+
125+
1. Should we enforce the prior art section via CI (e.g., a bot that checks for the section headers)?
126+
2. Should we maintain a living doc of "how OpenClaw/Hermes do X" to reduce per-PR research burden?
127+
3. Are there other mandatory reference projects beyond OpenClaw and Hermes?
128+
129+
---
130+
131+
## References
132+
133+
- [OpenClaw Channel & Messaging Deep Dive](https://avasdream.com/blog/openclaw-channels-messaging-deep-dive)
134+
- [Hermes Agent Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/)
135+
- PR #300 — example of a PR that would benefit from this guideline
136+
- RFC 001 — [Session Management](./001-session-management.md)

0 commit comments

Comments
 (0)