Skip to content

Commit ac6776b

Browse files
4ndrelim4ndrelim
authored
docs: add contributing instructions (#127)
## **Benefits** 1. **Clarity**: New contributors understand the workflow immediately 2. **Consistency**: Team follows the same practices 3. **AI-friendly**: Claude, Copilot, and other tools can learn project conventions 4. **Safety**: Clear rules prevent accidental breaking changes 5. **Flexibility**: Supports both careful testing and fast iteration --- ## Notes Refer to `CONTRIBUTING.md` for context. I've taken the liberty to make some assumptions / slight tweaks, explained below: 1. Proposed a simplified branch naming convention, using only prefixes `feat/*` and `fix/*`, but we enforce semantic classification (e.g. docs, chore, feat, fix, ci) in PR titles. [[1]](https://github.com/PaperDebugger/paperdebugger/pull/127/changes#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055R95-R96) 2. Note the standard branching flow (proposed to branch off `staging` before raising PR to `staging` and subsequently from `staging` to `main`) [[2]](https://github.com/PaperDebugger/paperdebugger/pull/127/changes#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055R95-R96) - Not sure if we should do this over branching off `main`. On one hand, `main` should always present the latest stable version, but it is also natural to branch off `staging` since it is the target branch of the merge after development. 4. Note the merging strategy [[3]](https://github.com/PaperDebugger/paperdebugger/pull/127/changes#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055R95-R96) **IMPORTANT NOTE**: 1. It seems `make test` is currently failing for some existing test cases. To investigate or inform the relevant owners. 2. @Junyi-99 I have disabled `Automatically request Copilot code review` for PRs to `main` but included it for PRs to `staging` since the new workflow expects heavy / complex changes to first PR to `staging` before `main`. To avoid double-review, i disabled this for PRs to `main`. Let me know if you would like to change or revert this. --- ## **Tasks** - [x] Create `CONTRIBUTING.md` with branching strategy section - [x] Configure branch protection rules in GitHub settings - [x] Set up automated version bumping (if not already configured) - [x] Document this in README.md or link to CONTRIBUTING.md - [ ] Announce new policy to team
1 parent 28ca8c8 commit ac6776b

2 files changed

Lines changed: 157 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Contributing to PaperDebugger
2+
3+
## Getting Started
4+
5+
**Prerequisites:** Go 1.24+, MongoDB, Node.js
6+
7+
```bash
8+
make deps # install dev tooling (linters, protoc, buf, wire, frontend deps)
9+
cp .env.example .env # configure environment variables
10+
docker run -d --name mongodb -p 27017:27017 mongo:latest # start MongoDB
11+
make build && ./dist/pd.exe # build and run
12+
```
13+
14+
See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed setup instructions.
15+
16+
## Branch Structure & Naming
17+
18+
| Branch | Purpose | Version Bump | Protection |
19+
|--------|---------|-------------|------------|
20+
| `main` | Production — every commit must be deployable | Minor (`2.1.x` → `2.2.0`) | Fully protected |
21+
| `staging` | Pre-production checkpoint, always aligned with or following `main` | Patch (`2.1.9` → `2.1.10`) | PR required, review optional |
22+
| `development` | Sandbox for rapid iteration and prod-env simulation | None | No restrictions |
23+
| `feat/*`, `fix/*` | Working branches for features and bug fixes | — | — |
24+
25+
Branch names are kept simple — use `feat/*` for new functionality and `fix/*` for bug fixes. The semantic distinction (docs, chore, refactor, etc.) is carried by the PR title instead (see [Pull Request Guidelines](#pull-request-guidelines)).
26+
27+
## Merge Workflow
28+
29+
### Standard Flow (substantial changes)
30+
31+
```
32+
feat/* or fix/* → staging → main
33+
↓ ↓
34+
integration production
35+
testing release
36+
```
37+
38+
1. Create `feat/*` or `fix/*` branch from `staging`
39+
2. Develop and test locally
40+
3. PR to `staging` — merge for integration testing on the staging endpoint
41+
4. Once no defects are found, PR from `staging` to `main`
42+
43+
### Fast-track Flow (small, isolated changes)
44+
45+
```
46+
feat/* or fix/* → main
47+
```
48+
49+
For small, well-tested changes (typo fixes, minor refactors) that don't need integration testing. PR review is still required.
50+
51+
> **Note:** Fast-track merges to `main` will cause `staging` to drift behind. This is fine — `staging` does not need to be in sync at all times. Sync `staging` with `main` before starting a new round of integration testing (e.g., merge `main` into `staging`).
52+
53+
### When to Use Which
54+
55+
| Use `staging` | Go direct to `main` |
56+
|---------------|---------------------|
57+
| Changes touch multiple components | Small, isolated changes |
58+
| Needs integration testing with recent changes | Confident in local testing |
59+
| Uncertain about production impact | Low-risk (typos, minor refactors) |
60+
| Want to verify on a prod-like environment first | — |
61+
62+
**Important:** Keep `staging` clean. It is the last gate before production — take care not to leave it in a broken state.
63+
64+
## Branch Protection
65+
66+
**`main`**
67+
- Pull request required (no direct pushes)
68+
- At least 1 approving review required
69+
- All status checks must pass
70+
- Linear history enforced (no merge commits)
71+
- Force pushes and deletions blocked
72+
73+
**`staging`**
74+
- Pull request required
75+
- Review optional, but **strongly recommended** for complex changes
76+
- All status checks must pass
77+
- Force pushes allowed (for rebasing)
78+
79+
**`development`**
80+
- No restrictions — free to push / merge without PR review
81+
- Useful for simulating production environment behavior
82+
83+
## Pull Request Guidelines
84+
85+
PR titles **must** follow [Conventional Commits](https://www.conventionalcommits.org/) format (enforced by CI). While branch names use simple `feat/*` or `fix/*` prefixes, the PR title carries the semantic meaning:
86+
87+
```
88+
feat: add tab completion support
89+
fix: resolve token expiration bug
90+
chore: update dependencies
91+
docs: improve setup instructions
92+
refactor: simplify chat service
93+
test: add citation parsing tests
94+
ci: add staging deploy workflow
95+
```
96+
97+
**Merge strategy:**
98+
- PR to `staging` — **merge commit** (retain full commit history for clarity and debugging during integration testing)
99+
- PR to `main` — **squash and merge** (one atomic, deployable commit per PR to keep history clean)
100+
101+
**Two-layer review process:**
102+
- PR to `staging` — first review layer, catches mistakes early (review optional but recommended)
103+
- PR to `main` — second review layer, always requires approval
104+
105+
## Version Numbering
106+
107+
We follow semantic versioning (`MAJOR.MINOR.PATCH`):
108+
109+
| Component | When | How |
110+
|-----------|------|-----|
111+
| **Major** (`X.0.0`) | Breaking changes | Manual |
112+
| **Minor** (`0.X.0`) | Merge to `main` | Auto-increment |
113+
| **Patch** (`0.0.X`) | Merge to `staging` | Auto-increment |
114+
115+
Example: `feat/new-feature` → staging (`2.1.9` → `2.1.10`) → main (`2.1.10` → `2.2.0`)
116+
117+
Minor and patch versions are bumped automatically via CI. For a **major version bump** (breaking changes), manually create a tag:
118+
119+
```bash
120+
git tag v3.0.0
121+
git push origin v3.0.0
122+
```
123+
124+
Subsequent automated bumps will increment from the new tag.
125+
126+
## Code Quality
127+
128+
Run these before submitting a PR:
129+
130+
```bash
131+
make fmt # format Go, proto, and frontend code
132+
make lint # lint Go (golangci-lint), proto (buf lint), and frontend (eslint)
133+
make test # run all tests with coverage (requires MongoDB on localhost:27017)
134+
```
135+
136+
All `make` commands and their details can be inspected in the [Makefile](Makefile).
137+
138+
**Code stability guarantee:** Every commit on `main` must:
139+
- Compile without errors
140+
- Pass all tests
141+
- Be deployable to production
142+
- Have no known breaking bugs
143+
144+
## Proto / API Changes
145+
146+
When modifying `.proto` files in `proto/`:
147+
148+
```bash
149+
make gen # regenerate Go + gRPC + gateway + TypeScript bindings
150+
```
151+
152+
Commit the generated files in `pkg/gen/` alongside your proto changes.

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ Stay connected with the PaperDebugger community! Join our [Discord](https://disc
4040
- [Custom Endpoint Configuration](#custom-endpoint-configuration)
4141
- [Architecture Overview](#architecture-overview)
4242
- [Self-Host Development Setup](#self-host-development-setup)
43+
- [Contributing](#contributing)
4344

4445
## Features
4546

@@ -103,6 +104,10 @@ The PaperDebugger backend is built with modern technologies:
103104

104105
Please refer to [DEVELOPMENT.md](docs/DEVELOPMENT.md).
105106

107+
## Contributing
108+
109+
Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for branch structure, merge workflow, PR guidelines, and code quality requirements.
110+
106111
## Citation
107112
```
108113
@misc{hou2025paperdebugger,

0 commit comments

Comments
 (0)