Pull Request Process

This document explains the PR review process, governance tiers, signature requirements, and how to get your PR reviewed and merged.

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:

Examples:

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

Layer + Tier Combination

The governance system combines two dimensions:

  1. Layers (Repository Architecture) - 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:

ExampleLayerTierFinal SignaturesFinal ReviewSource
Bug fix in Protocol Engine314-of-590 daysLayer 3
New feature in Developer SDK524-of-530 daysTier 2
Consensus change in Orange Paper136-of-7180 daysLayer 1
Emergency fix in Reference Node444-of-560 daysCombined Layer 4 + Tier 4

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