Nim Pr Guide

You know what maintainers value: small, focused changes with issue references and tests. You help contributors avoid the pitfalls that delay or kill PRs.

When working in ~/Development/Nim, you MUST:

1. Monitor branch size against thresholds (50/150/300 lines)
2. Before commits, analyze if changes should be a separate branch/PR
3. Ensure issue references exist for all work
4. Validate PR title/description format before submission
5. Check for test coverage on all changes

This is NOT optional. PRs that ignore these guidelines take weeks instead of hours. This is very important to my career as a Nim contributor.

Step 1: What is the current branch? Is it main/master or a feature branch? Step 2: What is the total diff size of this branch vs main? Step 3: Are there staged changes? How do they relate to existing branch changes? Step 4: Is there an issue reference for this work? Step 5: Are there tests for the changes? Step 6: Would this merge quickly, or would it stall?

Now proceed with confidence following Nim's contribution patterns.

Nim PR Guide Workflow

Automatic Triggers

This skill activates when:

Pre-Commit Analysis

Before EVERY commit in ~/Development/Nim, analyze whether staged changes belong in this branch.

Step 1: Get Current State

# Get branch name
git rev-parse --abbrev-ref HEAD

# Get merge base with main/devel
git merge-base HEAD devel  # or main

# Get existing branch changes (committed)
git diff $(git merge-base HEAD devel)...HEAD --stat

# Get staged changes
git diff --cached --stat

# Get combined size
git diff $(git merge-base HEAD devel) --stat

Step 2: Analyze Cohesion

Ask these questions about staged changes vs existing branch work:

Step 3: Split Decision

IF staged changes are UNRELATED to existing branch work:
  → Suggest: stash, create new branch, apply stash, commit there

IF staged changes are RELATED but branch would exceed 150 lines:
  → Suggest: commit current work, create continuation PR

IF staged changes are RELATED and branch stays under 150 lines:
  → Proceed with commit

Split Commands Template

# Stash current staged changes
git stash push -m "unrelated-work-for-new-branch"

# Create and switch to new branch from devel
git checkout devel
git checkout -b fix/ISSUE-NUMBER-brief-description

# Apply stashed changes
git stash pop

# Commit in new branch
git add .
git commit -m "fixes #ISSUE; description"

Size Thresholds

Size Check Command

# Check current branch size
git diff $(git merge-base HEAD devel) --stat | tail -1

# Example output: "5 files changed, 47 insertions(+), 12 deletions(-)"
# Total: 47 + 12 = 59 lines → "medium" territory

Issue Reference Requirements

Every PR MUST reference an issue. No exceptions for bug fixes.

If Issue Exists

Title format: fixes #ISSUE; Brief description

Examples:

• fixes #25341; Invalid C code for lifecycle hooks
• fixes #25284; .global initialization inside method hoisted

If No Issue Exists

For bug fixes:

1. Open issue first describing the bug
2. Wait for acknowledgment (even a label is enough)
3. Then submit PR referencing that issue

For new features:

1. Open RFC/discussion issue
2. Get explicit approval before coding
3. Only then submit PR

For docs/minor improvements:

• Can submit without issue, but use descriptive title
• Format: [Docs] Description or component: description

PR Title Formats

Most Successful (use these):

fixes #ISSUE_NUMBER; Brief description of what was fixed

fix COMPONENT: What was wrong and how it's fixed

For Documentation:

[Docs] Clear description of documentation change

Rules:

• Start lowercase UNLESS "Fixes", "Fix", or "[Category]"
• Keep under 72 characters
• Be specific, not generic

PR Description Templates

For Small Fixes (< 50 lines)

fixes #ISSUE_NUMBER

[Optional 1-2 sentence explanation if not obvious from code]

For Larger Changes (50+ lines)

fixes #ISSUE_NUMBER

## Summary
Brief explanation of what was broken and how this fixes it.

## Changes
- Specific change 1
- Specific change 2
- Added tests for X, Y, Z

[Optional: Technical details if complex]

For Refactoring Series

Continuation of #PREVIOUS_PR_NUMBER

## Changes in This PR
- Specific change 1
- Specific change 2

This is part X of Y in the COMPONENT refactoring series.

For Feature PRs (New Capabilities)

Use this format for PRs that introduce new functionality, especially those in a series:

# PR Title: Brief description of feature

**Base:** `devel` (or parent branch if in series)
**Branch:** `feature/branch-name`

---

Brief 1-2 sentence overview of what this PR introduces.

## Summary

1. **Capability 1**: Brief description
2. **Capability 2**: Brief description
3. **Feature detection**: Use `defined(nimHasFeatureName)` to check for this feature

## Example

\`\`\`nim
# Minimal working example demonstrating the feature
type
  Example[T] {.pragma: expression.} = object

static:
  doAssert condition  # Proves it works
\`\`\`

## Use Cases

### Use Case Title

Brief description of the problem this solves.

\`\`\`nim
# Before: the workaround
# After: the clean solution
\`\`\`

## Implementation

**Component** (`file.nim`):
- Change description 1
- Change description 2

**Another Component** (`other.nim`):
- Change description

## Tests

- `tests/path/to/test.nim` - Description of what's tested

## Dependencies

- Requires PRX (`branch-name`) for infrastructure  *(if part of series)*

## Prior Art *(optional)*

Reference related PRs/issues if this is an alternative approach.

For PR Series

When submitting related PRs as a series, include a summary table:

## Series Summary

| PR | Branch | Focus | Lines (net) |
|----|--------|-------|-------------|
| PR1 | `feature/first` | Infrastructure + X | +441 |
| PR2 | `feature/second` | Y functionality | +172 |
| PR3 | `feature/third` | Z functionality | +300 |

Together these PRs enable [combined capability description].

Pre-Submission Checklist

Run this checklist before creating any PR to nim-lang/Nim.

Required for ALL PRs:

• Branch size is under 150 lines (or justified)
• Issue reference exists in title (fixes #ISSUE)
• Title follows format: lowercase unless Fix/Fixes/[Category]
• Tests exist for the change
• All CI passes (or failures are clearly unrelated)
• No unrelated changes mixed in

Additional for 50+ line PRs:

• Description has ## Summary section
• Description has ## Changes bullet points
• Changes are cohesive (single purpose)

Additional for New Features:

• Prior discussion/approval exists
• Documentation added to manual
• Comprehensive test coverage

Additional for UI/Docs:

• Before/after screenshots if visual change

What Maintainers Prioritize

Based on comment analysis of 154 merged PRs:

Dependent PR Chains

When work naturally divides into multiple dependent PRs, the Nim project has implicit patterns based on contributor experience.

The Problem with PR Chains

GitHub does not natively support stacked/dependent PRs. Each subsequent PR in a chain contains all changes from preceding PRs until those are merged. This creates:

• Difficult-to-review diffs (reviewers see accumulated changes)
• Risk of wasted effort (if base PR is rejected, all descendants die)
• Merge conflict complexity when base PRs change during review

Recommended Approach: Sequential Submission

Wait for each PR to merge before submitting the next in a dependency chain.

Why this works:

• Each PR reviewed in isolation with clean diff
• No wasted effort on downstream PRs if base needs changes
• Clear review scope for maintainers
• Avoids confusing "depends on PR #X" gymnastics

Proven pattern (from contributor experience):

PR1: "System cleanup, part 1" → merged
PR2: "System cleanup, part 2" → submitted AFTER PR1 merged

Contributors who waited between submissions had higher merge success rates than those who submitted chains simultaneously.

When Sequential Isn't Possible

If you must have work visible before base merges (e.g., showing direction, getting early feedback):

Option A: Draft PR with explicit dependency

## ⚠️ Draft - Depends on #XXXX

This PR builds on #XXXX and should not be reviewed until that merges.
Once #XXXX merges, I will rebase and mark ready for review.

[Rest of description showing intended changes]

Option B: Combine into single PR (if truly tightly coupled)

• If changes genuinely cannot be separated meaningfully
• Use clear commit structure within the single PR
• Accept longer review time for larger scope

How to Communicate Dependencies

If submitting before base merges, include in PR description:

## Dependencies

- Requires #XXXX (feature/branch-name) to merge first

## Changes Specific to This PR

[List ONLY what this PR adds beyond the dependency]

What NOT to Do

1. Submitting full chain simultaneously - Creates review confusion, wastes effort if base rejected
2. Expecting reviewers to check out your branch - They review the GitHub diff
3. Hiding dependencies - Always explicitly state "depends on #X"
4. Reducing scope instead of proper splitting - When asked to split, create genuinely independent PRs, don't just remove features from existing PR
5. Creating continuation PRs before base is accepted - Wait for at least soft approval

Decision Framework for Dependencies

IF work is truly interdependent (A required for B to compile):
  → Submit A first, wait for merge, then submit B

IF work is conceptually related but independently valuable:
  → Submit as separate PRs targeting devel, not as chain

IF you want early feedback on full direction:
  → Submit base PR as ready, subsequent as Draft with explicit dependency note

IF base PR faces resistance:
  → Do NOT submit dependent PRs until base is accepted
  → Consider the chain dead if base is rejected

Series Naming

For related work that will be submitted sequentially:

• Use clear part numbers: "Feature X, part 1", "Feature X, part 2"
• Reference prior PRs: "Continuation of #XXXX"
• Each part should compile and pass tests independently

Common Pitfalls

1. No issue reference - Open issue first, then PR
2. Mixing fixes with refactoring - Separate PRs
3. Mixing features with fixes - Separate PRs
4. Optimizations without benchmarks - May be rejected
5. Infrastructure changes without discussion - 176+ day review cycles
6. Breaking changes without RFC - Won't be merged
7. Missing tests - Will be requested, delays merge
8. Generic titles - "Patch 24922" tells reviewer nothing
9. Submitting dependent PRs before base merges - Risk of wasted effort

Proactive Warnings

When to Warn User

Quick Commands

# Check branch size
git diff $(git merge-base HEAD devel) --stat | tail -1

# Check if branch references an issue (in commit messages)
git log $(git merge-base HEAD devel)..HEAD --oneline | grep -E '#[0-9]+'

# Preview PR title from branch name
echo "fixes #$(echo $(git rev-parse --abbrev-ref HEAD) | grep -oE '[0-9]+')"

# Check which files changed
git diff $(git merge-base HEAD devel) --name-only

# Check test files exist
git diff $(git merge-base HEAD devel) --name-only | grep -E 'tests?/'

See references/pr-guidelines.md for complete research data and examples. See references/split-detection.md for detailed split analysis logic.

• Did I check branch size against thresholds?
• Did I analyze if staged changes belong in this branch?
• Is there an issue reference for this work?
• Do tests exist for the changes?
• Is the PR title in correct format?
• Is the change focused (single purpose)?

If NO to ANY item, address before proceeding.

73% of merged PRs are under 50 lines. Fast-track merges are small bug fixes with tests. Maintainers value correctness, tests, and issue-driven development.

ALWAYS check branch size before committing. ALWAYS analyze if changes should be split. ALWAYS ensure issue references exist. NEVER let a branch exceed 300 lines without splitting.

This is very important to my career as a Nim contributor. Strive for excellence. Small, focused, tested changes get merged. Large, unfocused changes die.