Pull Request Process

For human maintainer expectations and the AI review intelligence operating document (alternative implementation vs Core fork, flags, Compact alignment), see Review standards.

Overview

BLVM uses a 5-tier constitutional governance model with cryptographic signatures to ensure secure, transparent, and accountable code changes. Every PR is automatically classified into a governance tier based on the scope and impact of the changes.

PR Lifecycle

1. Developer Opens PR

When you open a Pull Request:

1. Automated CI runs - Tests, linting, and build verification
2. Governance tier classification - PR is automatically classified (with temporary manual override available)
3. Status checks appear - Shows what needs to happen for merge

2. Maintainers Review and Sign

Maintainers review your code and cryptographically sign approval:

1. Review PR - Understand the change and its impact
2. Generate signature - Use blvm-sign from blvm-sdk
3. Post signature - Comment /governance-sign <signature> on PR
4. Governance App verifies - Cryptographically verifies signature
5. Status check updates - Shows signature count progress

3. Review Period Elapses

Each tier has a specific review period that must elapse:

• Tier 1: 7 days
• Tier 2: 30 days
• Tier 3: 90 days
• Tier 4: 0 days (immediate)
• Tier 5: 180 days

The review period starts when the PR is opened and all required signatures are collected.

4. Requirements Met → Merge Enabled

Once all requirements are met:

• Required signatures collected
• Review period elapsed
• All CI checks pass

The PR can be merged.

Governance Tiers

Tier 1: Routine Maintenance

Scope: Bug fixes, documentation, performance optimizations

Requirements:

• Signatures: 3-of-5 maintainers
• Review Period: 7 days
• Restriction: Non-consensus changes only

Examples:

• Fixing a typo in documentation
• Performance optimization in non-consensus code
• Bug fix in node networking code
• Code refactoring

Tier 2: Feature Changes

Scope: New RPC methods, P2P changes, wallet features

Requirements:

• Signatures: 4-of-5 maintainers
• Review Period: 30 days
• Requirement: Must include technical specification

Examples:

• Adding a new RPC method
• Implementing a new P2P protocol feature
• Adding wallet functionality
• New SDK features

Tier 3: Consensus-Adjacent

Scope: Changes affecting consensus validation code

Requirements:

• Signatures: 5-of-5 maintainers
• Review Period: 90 days
• Requirement: Formal verification (BLVM Specification Lock) required

Examples:

• Changes to consensus validation logic
• Modifications to block/transaction validation
• Updates to consensus-critical algorithms

Note: This tier requires the most scrutiny because changes can affect network consensus.

Tier 4: Emergency Actions

Scope: Critical security patches, network-threatening bugs

Requirements:

• Signatures: 4-of-5 maintainers
• Review Period: 0 days (immediate)
• Requirement: Post-mortem required

Severity classes (incident path; see Emergency Procedures):

• Critical: network-threatening (short maximum duration once activated)
• Urgent security: serious issues (intermediate duration cap)
• Elevated priority: important but not critical (longer cap)

Examples:

• Critical security vulnerability
• Network-threatening bug
• Consensus-breaking issue requiring immediate fix

Tier 5: Governance Changes

Scope: Changes to governance rules themselves

Requirements:

• Signatures: Special process (5-of-7 maintainers + 2-of-3 emergency keyholders): see governance policy and action tiers (not the action-tiers.yml row alone)
• Review Period: 180 days

Examples:

• Changing signature requirements
• Modifying review periods
• Updating governance tier definitions

Layer + Tier Combination

The governance system combines two dimensions:

1. Layers (repository layout) - Which repository the change affects
2. Tiers (Action Classification) - What type of change is being made

When both apply, the system uses "most restrictive wins" rule:

See Layer-Tier Model for the complete decision matrix.

Signature Requirements by Layer

In addition to tier requirements, layers have their own signature requirements:

• Layer 1-2 (Constitutional): 6-of-7 maintainers, 180 days (365 days for consensus changes)
• Layer 3 (Implementation): 4-of-5 maintainers, 90 days
• Layer 4 (Application): 3-of-5 maintainers, 60 days
• Layer 5 (Extension): 2-of-3 maintainers, 14 days

The most restrictive requirement (layer or tier) applies.

Maintainer Signing Process

How Maintainers Sign

1. Review PR: Understand the change and its impact
2. Generate signature: Use blvm-sign from blvm-sdk:

blvm-sign --message "Approve PR #123" --key ~/.blvm/maintainer.key

3. Post signature: Comment on PR:

/governance-sign <signature>

4. Governance App verifies: Cryptographically verifies signature
5. Status check updates: Shows signature count progress

Signature Verification

The Governance App cryptographically verifies each signature:

• Uses secp256k1 ECDSA (Bitcoin-compatible)
• Verifies signature matches maintainer's public key
• Ensures signature is for the correct PR
• Prevents signature reuse

Emergency Procedures

The numbered governance tiers (Tier 1-5) above describe normal pull-request classification. Emergency response classes are a separate axis: when incident handling is escalated, parameters follow the governance repo's config/emergency-tiers.yml (activation by 5-of-7 emergency keyholders, then the thresholds below). Do not confuse "Critical emergency" here with governance Tier 1, which means routine maintenance PRs.

Governance Tier 4 (PR classification for emergency merges) remains 4-of-5 maintainers and 0-day review as in the Tier 4 section above. The classes below describe post-activation incident governance on the wider maintainer pool where the YAML specifies 7 eligible signers.

Critical emergency (network-threatening)

• Review period: 0 days
• Maintainer signatures: 4-of-7 (per emergency-tiers.yml)
• Activation: 5-of-7 emergency keyholders
• Maximum duration: 7 days

Urgent security issue

• Review period: 7 days
• Maintainer signatures: 5-of-7
• Activation: 5-of-7 emergency keyholders
• Maximum duration: 30 days

Elevated priority

• Review period: 30 days
• Maintainer signatures: 6-of-7
• Activation: 5-of-7 emergency keyholders
• Maximum duration: 90 days

How to Get Your PR Reviewed

1. Ensure PR is Ready

• All CI checks pass
• Code is well-documented
• Tests are included
• PR description is clear

2. Be Patient

Effective review time is set by combining repository layer and governance tier (most restrictive wins). The bullets below are tier-only floors where the layer does not impose something stricter, for example, a Tier 1 change in a Layer 3 repository can still require 90 days (see the matrix in the Layer-Tier Model).

• Tier 1: 7 days minimum when layer allows
• Tier 2: 30 days minimum when layer allows
• Tier 3: 90 days minimum when layer allows
• Tier 4: 0 days (immediate once signatures and checks are met)
• Tier 5: 180 days minimum when layer allows

3. Respond to Feedback

• Address review comments promptly
• Update PR as needed
• Keep PR description current

4. Keep PRs Small

• Smaller PRs are reviewed faster
• Easier to understand
• Less risk of issues

5. Communicate

• Update PR description if scope changes
• Respond to questions
• Ask for help if stuck

PR Status Indicators

Your PR will show status indicators:

• Signature progress: 3/5 signatures collected
• Review period: 5 days remaining
• CI status: All checks passing/failing

Common Questions

How do I know what tier my PR is?

The Governance App automatically classifies your PR. You'll see the tier in the PR status checks.

Can I speed up the review process?

No. Effective review periods are fixed by layer + tier rules to ensure adequate scrutiny. However, you can:

• Ensure your PR is ready (all checks pass)
• Respond to feedback quickly
• Keep PRs small and focused

What if I disagree with the tier classification?

Contact maintainers. There's a temporary manual override available for tier classification.

Can I merge my own PR?

No. All PRs require maintainer signatures and review period to elapse, regardless of who opened it.

Additional Resources

• Contributing Guide - Complete developer workflow
• Governance Model - Detailed governance documentation
• Layer-Tier Model - Complete decision matrix