py-libp2p PR Preparation & Pre-Flight Validator
Automates the rigorous pre-flight checks required by the py-libp2p CI pipeline. Validates mandatory towncrier newsfragments, runs formatting, typechecks with mypy, executes tests, and verifies public interface integrity before pushing to upstream.
Trigger Phrases
| User Input |
Target Action |
| "Prepare PR for py-libp2p" / "Check my py-libp2p PR" |
Run full pre-flight audit: newsfragments, make pr, git status |
| "Create newsfragment for issue #1428" |
Generate formatted <ISSUE_NUMBER>.<TYPE>.rst with ReST rules |
| "Validate newsfragments" |
Run python ./newsfragments/validate_files.py and towncrier check |
| "Check if my changes break py-libp2p interfaces" |
Audit libp2p/abc.py for interface method regressions |
Step 1: Newsfragment Management (CI Blocker)
Newsfragments are mandatory for every PR in py-libp2p. Missing or malformed fragments will fail CI immediately.
Naming Convention
newsfragments/<ISSUE_OR_PR_NUMBER>.<TYPE>.rst
Valid Fragment Types
| Type |
Description |
feature.rst |
New user-facing capability or API addition |
bugfix.rst |
Fix for a bug or incorrect behavior |
breaking.rst |
Breaking change to public interfaces or behavior |
deprecation.rst |
Deprecating an existing API or feature |
docs.rst |
Documentation improvements, guides, or docstrings |
performance.rst |
Performance or memory optimizations |
removal.rst |
Removal of previously deprecated functionality |
internal.rst |
Internal refactoring, CI updates, test improvements |
misc.rst |
Trivial fixes, dependency updates, typo corrections |
Critical Content Rules
- User-Facing Perspective: Write what changed from the perspective of a library user, not internal code details.
- ❌ Bad: "Added helper method
_read_frame in yamux stream."
- ✅ Good: "Fixed a bug in Yamux where incoming short frames could cause premature stream truncation."
- ReStructuredText Syntax: Use valid ReST markup. Backticks around code:
`Yamux`.
- Mandatory Trailing Newline: The
.rst file MUST end with an explicit newline character (\n).
Validation Command
# Run inside py-libp2p root
python ./newsfragments/validate_files.py
towncrier build --draft --version preview
Step 2: Full Build & Verification Pipeline
Run the exact target executed by GitHub Actions:
# Activate repository virtual environment
source .venv/bin/activate || source venv/bin/activate
# Execute full verification: clean -> fix -> lint -> typecheck -> test
make pr
Targeted Fixes for Common Failures:
Step 3: Documentation Build Check
If changes touch .rst, .md, docstrings, or anything under docs/:
make linux-docs
Ensure no Sphinx warnings are treated as errors (-W).
Step 4: Interface Compliance Check
Inspect changes against libp2p/abc.py. Public interfaces must maintain compatibility:
| Interface Class |
Responsibility |
INetwork |
Network layer, peer connections, listeners |
ITransport |
Transport dialing and listening (TCP, QUIC, WS) |
IListener |
Inbound transport listener |
INetStream / IStream |
Multiplexed stream read/write/close |
IMuxedConn |
Stream multiplexer connection (Yamux, Mplex) |
ISecureConn |
Authenticated, encrypted channel (Noise, TLS) |
IPeerStore |
Peer addresses, keys, and protocols repository |
[!WARNING]
Renaming or removing any method on these interfaces is a breaking change and requires a .breaking.rst newsfragment and major/minor semver bump.
Output Template for Review
# 🚀 py-libp2p Pre-Flight Report
- **Branch:** `<branch-name>`
- **Linked Issue(s):** `#<issue-number>`
- **Newsfragment:** `newsfragments/<number>.<type>.rst` (✅ Validated / ❌ Missing)
### Verification Summary
| Check | Command | Status | Notes |
|---|---|---|---|
| **Newsfragments** | `python ./newsfragments/validate_files.py` | ✅ Passed | Valid towncrier draft |
| **Code Formatting** | `make fix && make lint` | ✅ Passed | Ruff formatting clean |
| **Type Checking** | `make typecheck` | ✅ Passed | Mypy 0 errors |
| **Test Suite** | `pytest tests/...` | ✅ Passed | All relevant tests passing |
| **Interface ABI** | `libp2p/abc.py` check | ✅ Untouched | No public breaking changes |
### Next Steps to Push
```bash
git add newsfragments/ <changed-files>
git commit -m "fix(yamux): handle short reads on stream (#<issue>)"
git push origin <branch-name>
1---2name: pylibp2p-pr-prep3description: Pre-flight validation, newsfragment generation, and PR readiness checklist for the py-libp2p repository. Validates towncrier newsfragments, runs lint/typecheck/tests via `make pr`, checks docs via `make linux-docs`, and audits public interface compliance (`INetwork`, `ITransport`, `IStream`, `IMuxedConn`). Use when the user says "prepare PR for py-libp2p", "create newsfragment", "check py-libp2p PR", "run make pr", "validate newsfragments", or is preparing to submit a PR to py-libp2p.4license: MIT5---67# py-libp2p PR Preparation & Pre-Flight Validator89Automates the rigorous pre-flight checks required by the `py-libp2p` CI pipeline. Validates mandatory towncrier newsfragments, runs formatting, typechecks with mypy, executes tests, and verifies public interface integrity before pushing to upstream.1011---1213## Trigger Phrases1415| User Input | Target Action |16|---|---|17| "Prepare PR for py-libp2p" / "Check my py-libp2p PR" | Run full pre-flight audit: newsfragments, `make pr`, git status |18| "Create newsfragment for issue #1428" | Generate formatted `<ISSUE_NUMBER>.<TYPE>.rst` with ReST rules |19| "Validate newsfragments" | Run `python ./newsfragments/validate_files.py` and towncrier check |20| "Check if my changes break py-libp2p interfaces" | Audit `libp2p/abc.py` for interface method regressions |2122---2324## Step 1: Newsfragment Management (CI Blocker)2526Newsfragments are **mandatory** for every PR in `py-libp2p`. Missing or malformed fragments will fail CI immediately.2728### Naming Convention29```text30newsfragments/<ISSUE_OR_PR_NUMBER>.<TYPE>.rst31```3233### Valid Fragment Types34| Type | Description |35|---|---|36| `feature.rst` | New user-facing capability or API addition |37| `bugfix.rst` | Fix for a bug or incorrect behavior |38| `breaking.rst` | Breaking change to public interfaces or behavior |39| `deprecation.rst` | Deprecating an existing API or feature |40| `docs.rst` | Documentation improvements, guides, or docstrings |41| `performance.rst` | Performance or memory optimizations |42| `removal.rst` | Removal of previously deprecated functionality |43| `internal.rst` | Internal refactoring, CI updates, test improvements |44| `misc.rst` | Trivial fixes, dependency updates, typo corrections |4546### Critical Content Rules471. **User-Facing Perspective:** Write what changed from the perspective of a library user, not internal code details.48 - ❌ Bad: *"Added helper method `_read_frame` in yamux stream."*49 - ✅ Good: *"Fixed a bug in Yamux where incoming short frames could cause premature stream truncation."*502. **ReStructuredText Syntax:** Use valid ReST markup. Backticks around code: `` `Yamux` ``.513. **Mandatory Trailing Newline:** The `.rst` file MUST end with an explicit newline character (`\n`).5253### Validation Command54```bash55# Run inside py-libp2p root56python ./newsfragments/validate_files.py57towncrier build --draft --version preview58```5960---6162## Step 2: Full Build & Verification Pipeline6364Run the exact target executed by GitHub Actions:6566```bash67# Activate repository virtual environment68source .venv/bin/activate || source venv/bin/activate6970# Execute full verification: clean -> fix -> lint -> typecheck -> test71make pr72```7374### Targeted Fixes for Common Failures:75- **Lint / Formatting issues:** Run `make fix` (applies ruff and autofixes).76- **Typecheck errors:** Run `make typecheck` (invokes `mypy --config-file tox.ini -p libp2p`).77- **Targeted Test Execution:** If full `make test` is too slow, run the specific test file:78 ```bash79 pytest tests/core/host/test_ping.py -v80 ```8182---8384## Step 3: Documentation Build Check8586If changes touch `.rst`, `.md`, docstrings, or anything under `docs/`:8788```bash89make linux-docs90```9192Ensure no Sphinx warnings are treated as errors (`-W`).9394---9596## Step 4: Interface Compliance Check9798Inspect changes against `libp2p/abc.py`. Public interfaces must maintain compatibility:99100| Interface Class | Responsibility |101|---|---|102| `INetwork` | Network layer, peer connections, listeners |103| `ITransport` | Transport dialing and listening (TCP, QUIC, WS) |104| `IListener` | Inbound transport listener |105| `INetStream` / `IStream` | Multiplexed stream read/write/close |106| `IMuxedConn` | Stream multiplexer connection (Yamux, Mplex) |107| `ISecureConn` | Authenticated, encrypted channel (Noise, TLS) |108| `IPeerStore` | Peer addresses, keys, and protocols repository |109110> [!WARNING]111> Renaming or removing any method on these interfaces is a **breaking change** and requires a `.breaking.rst` newsfragment and major/minor semver bump.112113---114115## Output Template for Review116117```markdown118# 🚀 py-libp2p Pre-Flight Report119120- **Branch:** `<branch-name>`121- **Linked Issue(s):** `#<issue-number>`122- **Newsfragment:** `newsfragments/<number>.<type>.rst` (✅ Validated / ❌ Missing)123124### Verification Summary125| Check | Command | Status | Notes |126|---|---|---|---|127| **Newsfragments** | `python ./newsfragments/validate_files.py` | ✅ Passed | Valid towncrier draft |128| **Code Formatting** | `make fix && make lint` | ✅ Passed | Ruff formatting clean |129| **Type Checking** | `make typecheck` | ✅ Passed | Mypy 0 errors |130| **Test Suite** | `pytest tests/...` | ✅ Passed | All relevant tests passing |131| **Interface ABI** | `libp2p/abc.py` check | ✅ Untouched | No public breaking changes |132133### Next Steps to Push134```bash135git add newsfragments/ <changed-files>136git commit -m "fix(yamux): handle short reads on stream (#<issue>)"137git push origin <branch-name>138```139```
sumanjeet0012