Skip to content

Commit 520fc5d

Browse files
GiggleLiuclaude
andcommitted
Simplify contributor guide: file an issue, we implement it
Lower the understanding barrier for contributors: - Lead with "no programming required" and a 3-step flow - Add community calls section (coming soon via Zulip) - Update reduction graph legend for new model categories - Update design.md module table for new category names Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 6f7358b commit 520fc5d

3 files changed

Lines changed: 29 additions & 31 deletions

File tree

README.md

Lines changed: 11 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -63,31 +63,22 @@ See the [MCP documentation](https://codingthrust.github.io/problem-reductions/mc
6363

6464
## Contributing
6565

66-
### Authorship Recognition
66+
**No programming experience required.** You contribute domain knowledge; we handle the implementation.
6767

68-
**Contribute 10 non-trivial reduction rules and you will be automatically added to the author list of the paper.** AI tools handle the implementation — contributors focus on designing correct reductions and test cases.
68+
1. **File an issue** — use the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Describe the problem or reduction you have in mind — the template guides you through the details.
69+
2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested pull request.
70+
3. **You review it** — you'll be mentioned on the PR to provide feedback. We present the implementation and iterate until you're satisfied.
6971

70-
### How to Contribute
72+
**Community calls** (coming soon via [Zulip](https://zulip.com/)): all issue contributors will be invited. Maintainers walk through recent implementations so you can ask questions and give feedback in real time.
7173

72-
1. **Open an issue** using the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Fill in all sections — the templates guide you through the required information (definition, algorithm, size overhead, example instance, etc.).
74+
**Authorship:** contribute 10 non-trivial reduction rules and you'll be added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).
7375

74-
**Hint:** If you use Claude Code / OpenCode / Codex (assume `gh` CLI tool and `superpowers` plugin are installed), you can just type:
75-
```
76-
File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
77-
```
78-
```
79-
File an issue on CodingThrust/problem-reductions, using the "Rule" issue template, about reduction from Closest Vector Problem to QUBO. Brainstorm with me.
80-
```
81-
Then AI agents will guide you to fill in the issue template.
76+
> **Tip:** If you use Claude Code / OpenCode / Codex, you can file issues interactively:
77+
> ```
78+
> File an issue on CodingThrust/problem-reductions, using the "Model" issue template, about the Closest Vector Problem. Brainstorm with me.
79+
> ```
8280
83-
2. Our AI agents will pick up the issue and generate a plan to implement the reduction rule.
84-
3. You will be mentioned in the pull request, provide feedback to the AI agents. If you are satisfied with the plan, you can merge the PR.
85-
86-
Optionally, if you prefer to **implement yourself**, I will recommend you to use the [superpowers:brainstorming](https://github.com/obra/superpowers) skill to help you write a detailed plan. Create a PR and let maintainers help review and merge the PR.
87-
88-
### Developer Commands
89-
90-
Run `make help` to see all available targets. See [CLAUDE.md](https://codingthrust.github.io/problem-reductions/claude.html) for the full command list and architecture details.
81+
If you prefer to **implement yourself**, see the [Design](https://codingthrust.github.io/problem-reductions/design.html) guide. Run `make help` to see available developer commands.
9182
9283
## Acknowledgments
9384

docs/src/design.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ This guide covers the library internals for contributors.
1717

1818
| Module | Purpose |
1919
|--------|---------|
20-
| [`src/models/`](#problem-model) | Problem type implementations (SAT, Graph, Set, Optimization) |
20+
| [`src/models/`](#problem-model) | Problem implementations by input structure: `graph/`, `formula/`, `set/`, `algebraic/`, `misc/` |
2121
| [`src/rules/`](#reduction-rules) | Reduction rules with `ReduceTo` implementations |
2222
| [`src/registry/`](#reduction-graph) | Reduction graph metadata (collected via `inventory`) |
2323
| [`src/solvers/`](#solvers) | BruteForce and ILP solvers |

docs/src/introduction.md

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@
1414
<div id="cy-controls">
1515
<div id="legend">
1616
<span class="swatch" style="background:#c8f0c8;"></span>Graph
17+
<span class="swatch" style="background:#c8c8f0;"></span>Formula
1718
<span class="swatch" style="background:#f0c8c8;"></span>Set
18-
<span class="swatch" style="background:#f0f0a0;"></span>Optimization
19-
<span class="swatch" style="background:#c8c8f0;"></span>Satisfiability
20-
<span class="swatch" style="background:#f0c8e0;"></span>Specialized
19+
<span class="swatch" style="background:#f0f0a0;"></span>Algebraic
20+
<span class="swatch" style="background:#f0c8e0;"></span>Misc
2121
<span style="display:inline-block;width:20px;height:0;border-top:2px dashed #bbb;margin-left:10px;margin-right:3px;vertical-align:middle;"></span>Variant Cast
2222
</div>
2323
<div>
@@ -62,14 +62,21 @@ This library is the foundation of that effort: an open-source, extensible reduct
6262

6363
## Call for Contributions
6464

65-
> **Everyone can contribute — no programming experience required.** If you know a computational problem or a reduction rule, just describe it in a GitHub issue. AI will generate a tested pull request for you to review.
66-
>
67-
> **Contribute 10 non-trivial reduction rules and you will be automatically added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).**
65+
> **No programming experience required.** You contribute domain knowledge — we handle the implementation.
6866
69-
1. **Open an issue** using the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template
70-
2. **Fill in all sections** — definition, algorithm, size overhead, example instance
71-
3. **Review AI-generated code** — AI generates code and you can comment on the pull request
72-
4. **Merge** — ask maintainers' assistance to merge once you are satisfied
67+
### How it works
68+
69+
1. **File an issue** — use the [Problem](https://github.com/CodingThrust/problem-reductions/issues/new?template=problem.md) or [Rule](https://github.com/CodingThrust/problem-reductions/issues/new?template=rule.md) template. Describe the problem or reduction you have in mind; the template guides you through the details.
70+
2. **We implement it** — for reasonable requests, maintainers tag the issue `implement` and AI agents generate a tested pull request.
71+
3. **You review it** — you'll be mentioned on the PR to provide feedback. We iterate until you're satisfied.
72+
73+
### Community calls
74+
75+
Coming soon via [Zulip](https://zulip.com/). All issue contributors will be invited. Maintainers walk through recent implementations so you can ask questions and give feedback in real time.
76+
77+
### Authorship
78+
79+
Contribute 10 non-trivial reduction rules and you'll be added to the author list of the [paper](https://codingthrust.github.io/problem-reductions/reductions.pdf).
7380

7481
For manual implementation, see the [Design](./design.md#contributing) guide.
7582

0 commit comments

Comments
 (0)