Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
128 lines (86 loc) · 3.99 KB

CONTRIBUTING.md

File metadata and controls

128 lines (86 loc) · 3.99 KB

Contributing

Making Changes

Branching

  • main is the stable branch
  • Create feature branches for changes: git checkout -b add-lightning-method

Pull Request Checklist

Before submitting a PR:

  1. Build succeeds: make check passes
  2. Lint passes: make lint passes
  3. Version bumped: If modifying a spec, increment the version number in the filename and frontmatter
  4. References are stable: Avoid new hardcoded external references like Section X.Y of {{I-D...}}

Types of Changes

Change Type Process
Typo/editorial fix Direct PR to main
New intent Use intent template, add to specs/intents/
New method Use method template, add to specs/methods/
New extension Use extension template, add to specs/extensions/
New method with experimental intent Define intent in method spec, add to specs/methods/
Core protocol change Open an issue first for discussion

Experimental Intents

Methods may define new intent types that are not yet formalized in specs/intents/. These are considered experimental intents.

Intent Location Status Requirements
specs/intents/ Standardized Adopted by 2+ methods
specs/methods/ only Experimental Single method definition

Workflow for new intents:

  1. Propose with method: Define the intent semantics directly in your method spec (specs/methods/draft-{network}-{intent}-00.md). The intent is automatically experimental.

  2. Gain adoption: Other methods implement the same intent pattern in their own specs.

  3. Formalize: Once 2+ methods implement the intent, extract common semantics into specs/intents/draft-payment-intent-{name}-00.md.

Example: A session payment method might define:

specs/methods/draft-tempo-session-00.md     ← defines "session" intent (experimental)
specs/methods/draft-lightning-session-00.md ← second implementation
specs/intents/draft-payment-intent-session-00.md ← formalized after adoption

This ensures intents are battle-tested before standardization, preventing premature abstractions.

Naming Conventions

Type Pattern Example
Core draft-httpauth-payment-XX draft-httpauth-payment-00
Intent draft-payment-intent-{name}-XX draft-payment-intent-charge-00
Method draft-{network}-payment-method-XX draft-tempo-payment-method-00
Extension draft-payment-{feature}-XX draft-payment-discovery-00

Writing Style

See STYLE.md for RFC writing conventions and design principles.

AI-Assisted Contributions

If you use AI tools to help write specifications or code:

  1. You are responsible for the correctness and quality of the output
  2. Disclose significant AI assistance in your PR description
  3. Review all generated content for RFC compliance

Agent Skills

This repo ships Amp agent skills in .agents/skills/. Skills are loaded automatically when working in this repo. To install them globally (so they're available across all projects):

./scripts/install-skills.sh

Building the Specifications

Using Docker (recommended)

# Build the Docker image (first time only)
make docker-build

# Generate XML, HTML, TXT, and PDF artifacts
make build

# Run build + validation
make check

# Interactive shell for debugging
make shell

# Clean generated artifacts
make clean

Local Development

# Install dependencies
bundle install              # Ruby: kramdown-rfc
pip install -r requirements.txt  # Python: xml2rfc, rfclint

# Generate artifacts
./scripts/gen.sh

# With verbose output
./scripts/gen.sh --verbose

Generated Outputs

All outputs are written to artifacts/:

  • draft-*.xml - RFC XML (v3)
  • draft-*.html - HTML version
  • draft-*.txt - Plain text version
  • draft-*.pdf - PDF version