Skip to content

docs: comprehensive implementation status revamp and extensions framework guide#4

Open
shivv23 wants to merge 1 commit into
seetadev:masterfrom
shivv23:feat/comprehensive-status-and-extensions-guide
Open

docs: comprehensive implementation status revamp and extensions framework guide#4
shivv23 wants to merge 1 commit into
seetadev:masterfrom
shivv23:feat/comprehensive-status-and-extensions-guide

Conversation

@shivv23
Copy link
Copy Markdown

@shivv23 shivv23 commented May 8, 2026

Summary

This PR makes three improvements to the GossipSub documentation:

1. Implementation status overhaul (implementation-status.md)

The previous file was missing py-libp2p entirely (all six other implementations were listed) and lacked v1.0 / v1.1 columns, making it inconsistent with the README table.

Changes:

  • Added py-libp2p row across all tables (versions, extensions, improvements)
  • Added v1.0 and v1.1 columns to the versions table for completeness
  • Added Test Extension and Large Message Segmentation to the extensions table
  • Updated Rust v1.2 status () — rust-libp2p has had v1.2 for several releases
  • Updated Go and Rust v1.3 status with PR links
  • Verified and corrected py-libp2p's v1.1/v1.2 status against the source code
  • Added a reference links table for quick navigation to all repos and specs

2. Extensions framework guide (extensions/README.md) — NEW

A comprehensive guide to the GossipSub v1.3 Extensions Control Message framework, covering:

  • How capability advertisement works via ControlExtensions handshake
  • Field number allocation rules (canonical vs experimental ranges)
  • Protocol activation semantics (both peers must opt in)
  • Registered extension registry with field numbers and spec links
  • How to register a new experimental extension (step-by-step)
  • Extension lifecycle (Experimental → Working Draft → Candidate Recommendation)
  • Relationship between GossipSub versions and the extensions framework

This fills a gap where the extensions mechanism was documented only implicitly through the protobuf file and individual extension specs.

3. README sync

  • Added v1.3 column to the inline implementation status table
  • Added link to extensions/README.md from the specification list
  • Corrected py-libp2p v1.1 / v1.2 status (verified against libp2p/py-libp2p source)
  • Added link to implementation-status.md for the full per-extension breakdown

…work guide

- Add py-libp2p to implementation-status.md (was completely missing)
- Add v1.0, v1.1 columns to implementation-status.md for completeness
- Add Test Extension and Large Message Segmentation to extensions table
- Update Rust v1.2 status (verified: complete) and Go/Rust v1.3 status
- Add reference links section for easy navigation
- Create extensions/README.md: extensions framework documentation
  covering capability advertisement, field number allocation, protocol
  activation, extension lifecycle, and registered extension registry
- Update README.md to link to implementation-status.md and add v1.3 column
  to inline table; correct py-libp2p v1.1/v1.2 status (verified: both ✅)
@shivv23
Copy link
Copy Markdown
Author

shivv23 commented May 8, 2026

@seetadev @johannamoran — this PR revamps the implementation status tracking and adds a comprehensive extensions framework guide. The status tables were missing py-libp2p entirely (ironic given the C4GT project focus) and had several inaccuracies I've corrected against the actual source code. The extensions README fills a documentation gap that I think becomes more important as the Large Message Segmentation and other experimental extensions mature.

Would love your feedback, especially on:

  1. Whether the extensions README structure makes sense as a long-term home for the extension registry
  2. Any status corrections I might have missed for Go/Rust/JS implementations

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant