Skip to content

Commit 7147a94

Browse files
olaloisolalois
committed
docs: expand CONTRIBUTING guide and add PR template
- Add comprehensive CONTRIBUTING.md with branch model, conventional commits reference, setup instructions, snippet standards, and CI check table - Add .github/PULL_REQUEST_TEMPLATE.md with branch checklist, conventional-commit type selector, content checklist, and snippet-check reminder Closes #91
1 parent d16d6c9 commit 7147a94

2 files changed

Lines changed: 340 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+
## Summary
2+
3+
<!-- What does this PR change and why? One or two sentences is enough for small
4+
changes. Link the issue this resolves. -->
5+
6+
Closes #
7+
8+
---
9+
10+
## Type of change
11+
12+
<!-- Check all that apply -->
13+
14+
- [ ] `feat` — new page or substantial content addition
15+
- [ ] `fix` — corrects a factual error, broken link, or bad code example
16+
- [ ] `docs` — changes to meta-docs (CONTRIBUTING.md, README.md, templates)
17+
- [ ] `chore` — tooling, CI, config, or dependency update
18+
- [ ] `refactor` — content restructuring without meaning changes
19+
- [ ] `style` — formatting only
20+
21+
---
22+
23+
## Branch checklist
24+
25+
> Common mistakes that cause PRs to be redirected. Please verify before opening.
26+
27+
- [ ] I branched from `develop`, not `main`
28+
- [ ] This PR targets `develop`, not `main`
29+
- [ ] My PR title follows conventional commits format (e.g., `feat(guides): add stellar multisig guide`)
30+
31+
---
32+
33+
## Content checklist
34+
35+
- [ ] All new or modified pages have at least one code example (if applicable)
36+
- [ ] Code examples use TypeScript, `@wraith-protocol/sdk`, and the `Chain` enum — not raw strings
37+
- [ ] No marketing copy — descriptions explain what, not how great
38+
39+
---
40+
41+
## Snippet checklist
42+
43+
<!-- Required for any PR that adds or modifies .mdx files containing code fences -->
44+
45+
- [ ] I ran `pnpm run check:snippets` locally and it passes
46+
- [ ] All new TypeScript/JavaScript fences compile without errors
47+
- [ ] I used `no-check` only for intentionally illustrative pseudocode that cannot be made runnable
48+
49+
<!-- If you added `no-check` to any fences, explain why here: -->
50+
51+
---
52+
53+
## Screenshots or previews
54+
55+
<!-- For visual or structural changes, attach a screenshot or paste a rendered
56+
preview. Delete this section if not applicable. -->
57+
58+
---
59+
60+
## Additional notes
61+
62+
<!-- Anything reviewers should know: related PRs, known gaps, follow-up issues. -->

‎CONTRIBUTING.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
# Contributing to Wraith Protocol Docs
2+
3+
Thanks for helping improve the Wraith Protocol documentation. This guide covers
4+
everything you need to contribute — from branching strategy to getting your PR merged.
5+
6+
---
7+
8+
## Table of contents
9+
10+
1. [Branch model](#branch-model)
11+
2. [Getting started](#getting-started)
12+
3. [Making changes](#making-changes)
13+
4. [Commit messages](#commit-messages)
14+
5. [Opening a pull request](#opening-a-pull-request)
15+
6. [Code and snippet standards](#code-and-snippet-standards)
16+
7. [CI checks](#ci-checks)
17+
8. [Review process](#review-process)
18+
19+
---
20+
21+
## Branch model
22+
23+
> **The most common mistake new contributors make is branching from `main` and
24+
> targeting `main` in their PR. Please read this section carefully.**
25+
26+
| Branch | Purpose |
27+
| --------- | ----------------------------------------------------------------------- |
28+
| `develop` | **Trunk.** All work branches off here. All PRs target here. |
29+
| `main` | **Release.** Reflects what is live in production. Never push directly. |
30+
31+
```
32+
main ──────────────────────────────────────► (live / released)
33+
↑ periodic release merges
34+
develop ──────────────────────────────────────► (trunk)
35+
↑ your PRs merge here
36+
feature/ ──────────────────────►
37+
fix/ ──────────────────────►
38+
docs/ ──────────────────────►
39+
```
40+
41+
**Always branch from `develop`. Always target `develop` in your PR.**
42+
43+
`main` is updated only via controlled releases by maintainers. A PR targeting
44+
`main` will be redirected or closed.
45+
46+
---
47+
48+
## Getting started
49+
50+
### Prerequisites
51+
52+
- Node.js 22+
53+
- [pnpm](https://pnpm.io/) 10+
54+
55+
### Fork and clone
56+
57+
```bash
58+
# Fork the repo on GitHub, then:
59+
git clone https://github.com/<your-username>/docs.git
60+
cd docs
61+
62+
# Add upstream remote
63+
git remote add upstream https://github.com/wraith-protocol/docs.git
64+
```
65+
66+
### Install dependencies
67+
68+
```bash
69+
pnpm install
70+
```
71+
72+
### Sync with upstream before starting work
73+
74+
```bash
75+
git fetch upstream
76+
git checkout develop
77+
git merge upstream/develop
78+
```
79+
80+
### Create a branch
81+
82+
Branch names should use one of these prefixes:
83+
84+
| Prefix | When to use |
85+
| ---------- | ------------------------------------------------------- |
86+
| `feat/` | New page or substantial new section |
87+
| `fix/` | Correcting a factual error, broken link, or bad example |
88+
| `docs/` | Meta-docs changes (this file, README, templates) |
89+
| `chore/` | Config, CI, tooling, dependency updates |
90+
| `refactor/`| Restructuring content without changing meaning |
91+
92+
```bash
93+
git checkout -b feat/stellar-multisig-guide
94+
```
95+
96+
---
97+
98+
## Making changes
99+
100+
### File structure
101+
102+
Pages live at the repo root in their logical subdirectory. All content files are
103+
`.mdx`. Internal docs (like this file) are `.md`.
104+
105+
```
106+
CONTRIBUTING.md
107+
README.md
108+
getting-started.mdx
109+
sdk/
110+
guides/
111+
architecture/
112+
contracts/
113+
api-reference/
114+
```
115+
116+
See `CLAUDE.md` for the full content map.
117+
118+
### Writing style
119+
120+
- Short sentences. Active voice.
121+
- Technical but approachable — assume TypeScript knowledge, not stealth-address
122+
cryptography knowledge.
123+
- Every conceptual page needs at least one working code example.
124+
- Use `@wraith-protocol/sdk` as the package name. Reference the `Chain` enum,
125+
not raw strings. All code examples must be TypeScript.
126+
- No marketing copy. Describe what things do, not how great they are.
127+
128+
### MDX conventions
129+
130+
- Use `.mdx` extension for all public-facing docs.
131+
- Keep frontmatter minimal — `title` and `description` are sufficient for most
132+
pages.
133+
- Code fences must specify a language tag (e.g., ` ```typescript `).
134+
- Use `no-check` only for intentionally non-runnable pseudocode (see
135+
[snippet standards](#code-and-snippet-standards) below).
136+
137+
---
138+
139+
## Commit messages
140+
141+
All commits must follow [Conventional Commits](https://www.conventionalcommits.org/).
142+
143+
### Format
144+
145+
```
146+
<type>(<optional scope>): <short description>
147+
148+
[optional body]
149+
150+
[optional footer(s)]
151+
```
152+
153+
### Types
154+
155+
| Type | When to use |
156+
| ---------- | --------------------------------------------------------- |
157+
| `feat` | A new page, section, or meaningful content addition |
158+
| `fix` | Corrects an error — factual, typographical, or code-based |
159+
| `docs` | Changes to meta-docs (CONTRIBUTING.md, README.md, etc.) |
160+
| `chore` | Tooling, CI, config, dependency updates |
161+
| `refactor` | Content restructuring without meaning changes |
162+
| `style` | Formatting only (whitespace, punctuation) |
163+
164+
### Examples
165+
166+
```
167+
feat(guides): add stellar multisig withdrawal guide
168+
fix(sdk): correct Chain enum example in agent-client reference
169+
docs: expand CONTRIBUTING with branch model
170+
chore(ci): pin actions/checkout to v4
171+
refactor(architecture): reorganise TEE section headings
172+
```
173+
174+
### Rules
175+
176+
- Subject line: 72 characters max, lowercase, no trailing period.
177+
- Use the imperative mood — "add guide" not "added guide" or "adds guide".
178+
- Reference issues in the footer: `Closes #91`
179+
- **Do not** add `Co-Authored-By` lines.
180+
181+
---
182+
183+
## Opening a pull request
184+
185+
1. Push your branch to your fork:
186+
187+
```bash
188+
git push -u origin feat/your-branch-name
189+
```
190+
191+
2. Open a PR on GitHub. Set:
192+
- **Base branch:** `develop` ← your branch
193+
- **Title:** Follow the conventional commits format (e.g.,
194+
`feat(guides): add stellar multisig withdrawal guide`)
195+
196+
3. Fill in the PR template completely. Incomplete templates slow down review.
197+
198+
4. A maintainer will review within a few business days. Address feedback with
199+
new commits — do not force-push after a review has started.
200+
201+
### Common PR mistakes to avoid
202+
203+
| Mistake | Correct approach |
204+
| ----------------------------------- | ------------------------------------- |
205+
| Branching from `main` | Always branch from `develop` |
206+
| Targeting `main` in the PR | Always target `develop` |
207+
| No conventional-commit prefix in title | Use `feat:`, `fix:`, `docs:`, etc. |
208+
| Snippet check failing | Run `pnpm run check:snippets` locally first |
209+
| Opting out snippets with `no-check` when they could compile | Prefer making snippets compile |
210+
211+
---
212+
213+
## Code and snippet standards
214+
215+
All TypeScript and JavaScript code fences in `.mdx` files are validated by the
216+
snippet checker on every PR.
217+
218+
### Running the snippet check locally
219+
220+
```bash
221+
pnpm run check:snippets
222+
```
223+
224+
The checker extracts every ` ```ts `, ` ```tsx `, ` ```typescript `, ` ```js `,
225+
and ` ```javascript ` fence, writes it to a temp file, and runs `tsc --noEmit`
226+
against it. This catches syntax errors and malformed TypeScript before CI does.
227+
228+
### When a snippet fails
229+
230+
1. Fix the snippet so it compiles. This is the preferred path.
231+
2. If the snippet is intentionally illustrative pseudocode that is not meant to
232+
run, add `no-check` after the language tag:
233+
234+
````mdx
235+
```typescript no-check
236+
// This is pseudocode illustrating the concept only.
237+
const result = await someHypotheticalMethod();
238+
```
239+
````
240+
241+
Use `no-check` sparingly. A snippet that can be made to compile should be.
242+
243+
### Stellar testnet snippets
244+
245+
A separate non-blocking CI job validates Stellar-specific snippets against the
246+
live testnet. This job uses `continue-on-error: true` and will not block your
247+
PR from merging. If it fails, a maintainer will investigate separately.
248+
249+
---
250+
251+
## CI checks
252+
253+
| Check | Blocking | Description |
254+
| ---------------------------------- | -------- | ------------------------------------------ |
255+
| Compile docs snippets | ✅ Yes | Runs `pnpm run check:snippets` on every PR |
256+
| Stellar snippet testnet validation | ❌ No | End-to-end validation against Stellar testnet |
257+
258+
The blocking check must pass before a PR can be merged. You can see check
259+
status in the **Checks** tab of your PR.
260+
261+
---
262+
263+
## Review process
264+
265+
- Maintainers aim to review within **2 business days**.
266+
- All feedback should be addressed in new commits, not by rewriting history
267+
after review has started.
268+
- Once approved, a maintainer will squash-merge your PR into `develop`.
269+
- Squash message will follow conventional commits format, referencing your PR.
270+
- Periodic batches of `develop` → `main` are performed by maintainers as
271+
releases.
272+
273+
---
274+
275+
## Questions
276+
277+
Open an issue or start a discussion on GitHub. Tag it `question` so it gets
278+
routed to the right people.

0 commit comments

Comments
 (0)