Skip to content

Commit 2057e72

Browse files
Junyi-994ndrelimJunyi Houclaude
authored
chore: merge main into staging: add nodeSelector support (#137)
Co-authored-by: andre <95348273+4ndrelim@users.noreply.github.com> Co-authored-by: Junyi Hou <junyi@xtras3.tail08d22c.ts.net> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 54514a8 commit 2057e72

11 files changed

Lines changed: 195 additions & 0 deletions

‎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,

‎hack/values-dev.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
namespace: paperdebugger-dev
22

3+
nodeSelector:
4+
kubernetes.io/hostname: xtras3
5+
cloudflareNodeSelector:
6+
kubernetes.io/hostname: nuc
7+
38
mongo:
49
in_cluster: false

‎hack/values-prd.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
namespace: paperdebugger
22

3+
nodeSelector:
4+
kubernetes.io/hostname: xtras3
5+
cloudflareNodeSelector:
6+
kubernetes.io/hostname: nuc
7+
38
mongo:
49
in_cluster: false

‎hack/values-stg.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
namespace: paperdebugger-stg
22

3+
nodeSelector:
4+
kubernetes.io/hostname: xtras3
5+
cloudflareNodeSelector:
6+
kubernetes.io/hostname: nuc
7+
38
mongo:
49
in_cluster: false

‎helm-chart/templates/cloudflare.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ spec:
2323
labels:
2424
pod: cloudflared
2525
spec:
26+
{{- with .Values.cloudflareNodeSelector }}
27+
nodeSelector:
28+
{{- toYaml . | nindent 8 }}
29+
{{- end }}
2630
securityContext:
2731
sysctls:
2832
# Allows ICMP traffic (ping, traceroute) to resources behind cloudflared.

‎helm-chart/templates/mongo.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ spec:
1414
labels:
1515
app: mongo
1616
spec:
17+
{{- with $.Values.nodeSelector }}
18+
nodeSelector:
19+
{{- toYaml . | nindent 8 }}
20+
{{- end }}
1721
containers:
1822
- name: mongo
1923
image: {{ .Values.mongo.image }}

‎helm-chart/templates/paperdebugger-mcp.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ spec:
1313
labels:
1414
app: paperdebugger-mcp-server
1515
spec:
16+
{{- with .Values.nodeSelector }}
17+
nodeSelector:
18+
{{- toYaml . | nindent 8 }}
19+
{{- end }}
1620
imagePullSecrets:
1721
- name: ghcr-secret
1822
containers:

‎helm-chart/templates/paperdebugger-xtramcp-server.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ spec:
1313
labels:
1414
app: paperdebugger-xtramcp-server
1515
spec:
16+
{{- with .Values.nodeSelector }}
17+
nodeSelector:
18+
{{- toYaml . | nindent 8 }}
19+
{{- end }}
1620
imagePullSecrets:
1721
- name: ghcr-secret
1822
containers:

‎helm-chart/templates/paperdebugger.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ spec:
1313
labels:
1414
app: paperdebugger
1515
spec:
16+
{{- with .Values.nodeSelector }}
17+
nodeSelector:
18+
{{- toYaml . | nindent 8 }}
19+
{{- end }}
1620
imagePullSecrets:
1721
- name: ghcr-secret
1822
initContainers:

0 commit comments

Comments
 (0)