Skip to content

Commit acada4c

Browse files
authored
docs: add protocol/tag change scope guidelines and reviewer checklist (#677)
Closes #662
1 parent 3824649 commit acada4c

2 files changed

Lines changed: 21 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
- Commit subject: imperative, ≤50 chars; sign with `git commit -S`.
3737
- Squash fixups before review.
3838
- PRs: link the motivating issue, include `cargo test` output, and call out schema or config changes to ease verification.
39+
- **Protocol/tag changes:** prefer single-kind (single event domain) PRs. Cross-kind changes require a scope declaration and compatibility statement in the PR body (see `CONTRIBUTING.md § Protocol / Tag Changes`).
3940

4041
## Documentation Guidelines
4142
- Do not hardcode source code line numbers in documentation (e.g., `src/app/take_buy.rs:11`). Line numbers drift as the codebase evolves, misleading developers. Reference file paths (`src/app/take_buy.rs`) or function names (`fn take_buy_action`) instead, which are far more stable and easily searchable.

CONTRIBUTING.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,24 @@ All Mostro contributors submit changes via pull requests. The workflow is as fol
2121

2222
Pull requests should be focused on a single change. Do not mix, for example, refactorings with a bug fix or implementation of a new feature. This practice makes it easier for fellow contributors to review each pull request.
2323

24+
### Protocol / Tag Changes
25+
26+
Changes that affect Nostr event tags (e.g. `y` tags, `z` tags) or event kinds are **protocol changes** and deserve extra care:
27+
28+
- **Single-kind PRs preferred** – limit each PR to one event domain (orders, info, dispute, admin, dev-fee) whenever possible.
29+
- **Cross-kind changes** – if a PR must touch multiple event domains, include a "Scope Declaration" section in the PR body (see template below) and explain why the change cannot be split.
30+
- **Compatibility statement** – every protocol-tag PR must state the impact on external consumers (indexers, clients, relays).
31+
32+
#### PR Body Template for Protocol Changes
33+
34+
```markdown
35+
## Scope Declaration
36+
- **Event domains affected:** (e.g. orders, info, dispute)
37+
- **Cross-kind change:** yes / no
38+
- **Reason (if cross-kind):**
39+
- **External compatibility impact:** (indexers, clients, relays)
40+
```
41+
2442
## Reviewing Pull Requests
2543

2644
Mostro follows the review workflow established by the Bitcoin Core project. The following is adapted from the [Bitcoin Core contributor documentation](https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#peer-review):
@@ -33,6 +51,8 @@ Anyone may participate in peer review which is expressed by comments in the pull
3351
- `Concept ACK` means "I agree in the general principle of this pull request";
3452
- `Nit` refers to trivial, often non-blocking issues.
3553

54+
Reviewers should also verify **external contract impact** for any PR that modifies event kinds, tags, or message formats — confirm that indexers, clients, and relays are not silently broken by the change.
55+
3656
Please note that Pull Requests marked `NACK` and/or GitHub's `Change requested` are closed after 30 days if not addressed.
3757

3858
## Code formatting

0 commit comments

Comments
 (0)