Release Plan: py-mult* Repositories and py-libp2p

[acul71]

Release Plan: py-mult* Repositories and py-libp2p (Updated with Base58 Migration)

Overview

This document outlines the release plan for py-multihash, py-multibase, py-multicodec, py-cid, and py-libp2p. The order matters due to dependency relationships. This version includes the base58 to py-multicodec migration.

TL;DR

Release Order (must follow this sequence):

1. py-multihash 3.0.0 - Add type annotations (required by py-cid) DONE
2. py-multibase 2.0.0 - New release (can be parallel with define interfaces for milestone 1 #3) DONE
3. py-multicodec 2.0.0 - New release with base58 integration (can be parallel with added basic_host.py #2)
4. py-cid 0.4.0 - Migrate from pymultihash to py-multihash>=3.0.0 AND migrate base58 to py-multicodec>=2.0.0 (depends on added host folder & interface.py #1, added basic_host.py #2, define interfaces for milestone 1 #3)
5. py-libp2p 0.4.1 - Switch from fork to official py-multihash>=3.0.0 AND migrate base58 to py-multicodec>=2.0.0 (depends on added linter and style fixes #4)

Key Points:

• py-multihash needs type annotations added (currently only in fork) ✅ DONE
• py-multibase and py-multicodec are independent and can be released in parallel ✅ DONE
• py-multicodec 2.0.0 includes base58 functionality (eliminates need for separate base58 package)
• py-cid migrates from old pymultihash package to new py-multihash package AND migrates base58 to py-multicodec
• py-libp2p currently uses a fork of py-multihash and will switch to official version AND migrate base58 to py-multicodec
• All releases are required (not optional)

Dependency Chain

Verified Dependencies:

py-multihash (base)
    ↓
py-multibase (independent - no py-multihash dependency) [can be parallel]
    ↓
py-multicodec 2.0.0 (independent - no py-multibase/py-multihash dependency, includes base58) [can be parallel]
    ↓
py-cid (depends on: py-multihash, py-multibase, py-multicodec>=2.0.0 for base58)
    ↓
py-libp2p (depends on: py-multihash, py-cid via multiaddr, py-multicodec>=2.0.0 for base58)

Note: Arrows indicate release order, not dependency relationships. py-multibase and py-multicodec are independent and can be released in parallel with py-multihash.

Actual Dependencies:

• py-multibase: python-baseconv, six, morphys (NO py-multihash dependency)
• py-multicodec 2.0.0: varint (NO py-multibase or py-multihash dependency) + includes base58 functionality
• py-cid: py-multihash, py-multibase, py-multicodec>=2.0.0 (all three, uses py-multicodec for base58)
• py-libp2p: py-multihash (direct), py-cid (via multiaddr), py-multicodec>=2.0.0 (for base58)

Release Order and Steps

Phase 1: py-multihash (Foundation)

Repository: multiformats/py-multihash
Current Version: 2.0.1 (Dec 2020)
Target Version: 3.0.0

Step 1.1: Add Type Annotations

• Create PR to multiformats/py-multihash adding type annotations to Multihash class
  • PR Multiaddr to_options and validation #25: Add type annotations for Multihash namedtuple fields
  • Adds the following annotations:

    class Multihash(namedtuple("Multihash", "code,name,length,digest")):
        # Type annotations for namedtuple fields (for static type checkers)
        code: int
        name: str
        length: int
        digest: bytes

• Ensure digest() function is present (already in master branch)
• Get PR reviewed and approved
• Address any review feedback

Step 1.2: Release py-multihash 3.0.0

• Merge type annotations PR
• Update version to 3.0.0
• Update CHANGELOG with type annotation additions
• Run full test suite
• Create git tag: v3.0.0
• Build and upload to PyPI: py-multihash==3.0.0
• Verify PyPI package installs correctly
• Test with py-libp2p codebase (replace fork dependency)

Deliverable: py-multihash>=3.0.0 available on PyPI with type annotations ✅ DONE

---

Phase 2: py-multibase

Repository: multiformats/py-multibase
Current Version: 1.0.3
Target Version: 2.0.0

Verified: py-multibase does NOT depend on py-multihash. Dependencies are: python-baseconv, six, morphys

Status: New release required (not optional) ✅ DONE

Step 2.1: Prepare Release

• Review changes since 1.0.3
• Check if type annotations would be beneficial
• Verify compatibility with py-cid 0.4.0 requirements
• Update CHANGELOG/HISTORY.rst with changes

Step 2.2: Update Version and Release

• Update version to 2.0.0
• Add type annotations (if beneficial)
• Run full test suite
• Test compatibility with py-cid
• Create git tag: v2.0.0
• Build and upload to PyPI: py-multibase==2.0.0
• Verify PyPI package installs correctly

Deliverable: py-multibase>=2.0.0 available on PyPI (required for release chain) ✅ DONE

---

Phase 3: py-multicodec

Repository: multiformats/py-multicodec
Current Version: 0.2.1
Target Version: 2.0.0 (updated from 1.0.0 - base58 integration requires major version bump)

Verified: py-multicodec does NOT depend on py-multibase or py-multihash. Only depends on: varint

Status: New release required (not optional)

IMPORTANT: Version is 2.0.0 (not 1.0.0) because base58 integration is a significant feature addition that warrants a major version bump.

Step 3.1: Prepare Release

• Review changes since 0.2.1
• Verify base58 integration is complete in 2.0.0
• Ensure b58encode() and b58decode() functions are available
• Test base58 functionality before release
• Check if type annotations would be beneficial
• Verify compatibility with py-cid 0.4.0 requirements
• Update CHANGELOG/HISTORY.rst with changes
• Document base58 integration in CHANGELOG

Step 3.2: Update Version and Release

• Update version to 2.0.0 (major version bump due to base58 integration)
• Add type annotations (if beneficial)
• Run full test suite
• Test base58 encoding/decoding functionality
• Test compatibility with py-cid
• Create git tag: v2.0.0
• Build and upload to PyPI: py-multicodec==2.0.0
• Verify PyPI package installs correctly
• Verify base58 functions are accessible: from multicodec import b58encode, b58decode

Deliverable: py-multicodec>=2.0.0 available on PyPI with base58 integration (required for release chain)

Base58 Integration Notes:

• py-multicodec 2.0.0 includes base58 encoding/decoding functionality
• Eliminates need for separate base58 package
• API: from multicodec import b58encode, b58decode
• Functions: b58encode(data: bytes) -> bytes, b58decode(encoded: str) -> bytes

---

Phase 4: py-cid

Repository: ipld/py-cid
Maintainers: acul71, pacrob
Current Version: 0.3.1 (uses pymultihash and base58)
Target Version: 0.4.0 (with py-multihash migration AND base58 to py-multicodec migration)

Step 4.1: Update Dependencies

• Update pyproject.toml dependencies:

  dependencies = [
      # Remove: "base58>=1.0.2,<2.0",  # No longer needed - use py-multicodec
      "py-multibase>=2.0.0,<3.0.0",  # Updated to allow 2.0.0
      "py-multicodec>=2.0.0,<3.0.0",  # Updated: now includes base58 functionality
      "morphys>=1.0,<2.0",
      "py-multihash>=3.0.0",  # Updated to require type annotations
  ]

• Remove pymultihash dependency (old package)
• Remove base58 dependency (now provided by py-multicodec>=2.0.0)
• Update imports from pymultihash to multihash (py-multihash)

Step 4.1.5: Migrate base58 to py-multicodec

• Remove base58 dependency from pyproject.toml (already in Step 4.1)
• Add py-multicodec>=2.0.0 dependency (already in Step 4.1)
• Update all imports: import base58 → from multicodec import b58encode, b58decode
• Update function calls: base58.b58encode() → b58encode(), base58.b58decode() → b58decode()
• Verify py-cid uses base58 for CIDv0 encoding (base58-encoded multihash)
• Test CID encoding/decoding with new base58 implementation
• Ensure CIDv0 (base58-encoded) still works correctly

Step 4.2: Code Migration

• Update all imports in py-cid codebase
• Include base58 migration in code migration checklist
• Verify all base58 usage is updated
• Test API compatibility (pymultihash → py-multihash)
• Update any API calls that changed
• Run full test suite

Step 4.3: Testing

• Test with py-multihash 3.0.0 (with type annotations)
• Test base58 encoding/decoding with py-multicodec 2.0.0
• Verify CIDv0 (base58-encoded) still works correctly
• Test with py-libp2p codebase
• Test with multiaddr (which depends on py-cid)
• Verify type checking works (mypy/pyrefly)

Step 4.4: Release py-cid 0.4.0

• Update version to 0.4.0
• Update CHANGELOG with migration notes:
  • Migration from pymultihash to py-multihash>=3.0.0
  • Migration from base58 to py-multicodec>=2.0.0
• Create git tag: v0.4.0
• Build and upload to PyPI: py-cid==0.4.0
• Verify PyPI package installs correctly
• Test installation with dependencies

Deliverable: py-cid>=0.4.0 available on PyPI with py-multihash>=3.0.0 dependency and py-multicodec>=2.0.0 for base58

---

Phase 5: py-libp2p

Repository: libp2p/py-libp2p
Current Version: 0.4.0
Target Version: 0.4.1

Step 5.1: Update Dependencies

• Update pyproject.toml to use official py-multihash:

  dependencies = [
      # ... other dependencies ...
      "py-multicodec>=2.0.0",  # Includes base58 functionality
      "py-multihash>=3.0.0",  # Switch from fork to official
      # Remove: "base58>=1.0.3",  # No longer needed - use py-multicodec
      # Remove: "py-multihash @ git+https://github.com/sumanjeet0012/py-multihash.git@..."
  ]

• Update multiaddr dependency if needed (should get py-cid 0.4.0 automatically)
• Verify all py-mult* dependencies are up to date

Step 5.1.5: Migrate base58 to py-multicodec

• Remove base58>=1.0.3 dependency from pyproject.toml (already in Step 5.1)
• Add py-multicodec>=2.0.0 dependency (already in Step 5.1, already done in fix/multicodec-base58-dep branch)
• Update all imports in codebase:
  • libp2p/peer/id.py: import base58 → from multicodec import b58decode, b58encode
  • libp2p/pubsub/pubsub.py: import base58 → from multicodec import b58encode
  • libp2p/kad_dht/utils.py: import base58 → from multicodec import b58encode
  • examples/pubsub/floodsub.py: Update imports
  • examples/pubsub/pubsub.py: Update imports
  • tests/core/peer/test_peerid.py: Update imports
  • tests/core/relay/test_circuit_v2_transport.py: Update imports
• Update function calls: base58.b58encode() → b58encode(), base58.b58decode() → b58decode()
• Verify ID.from_base58() and ID.to_base58() methods work correctly
• Test all base58-related functionality

Note: The base58 migration has already been completed in the fix/multicodec-base58-dep branch. This step documents what was done.

Step 5.2: Remove Fork Dependency

• Remove git-based py-multihash dependency
• Test that official py-multihash 3.0.0 works
• Verify type annotations are recognized by mypy/pyrefly
• Fix any type checking errors that appear

Step 5.3: Code Updates

• Update any code that relied on fork-specific features
• Ensure all multihash API calls work with official version
• Test base58 encoding/decoding with py-multicodec 2.0.0
• Verify peer ID encoding/decoding works correctly
• Test pubsub message encoding
• Test DHT operations using base58
• Run full test suite
• Fix any breaking changes

Step 5.4: Testing

• Test with py-multihash 3.0.0
• Test with py-cid 0.4.0 (via multiaddr)
• Test with py-multicodec 2.0.0
• Test with all py-mult* packages
• Run type checking (mypy/pyrefly) - should pass without errors
• Run integration tests
• Test with examples

Step 5.5: Release py-libp2p 0.4.1

• Update version to 0.4.1
• Update CHANGELOG with:
  • Migration from base58 to py-multicodec>=2.0.0 (base58 now integrated)
  • Migration from fork to official py-multihash>=3.0.0
  • Type annotation improvements
  • Updated dependencies
• Create git tag: v0.4.1
• Build and upload to PyPI: libp2p==0.4.1
• Verify PyPI package installs correctly
• Test fresh installation with all dependencies

Deliverable: libp2p>=0.4.1 available on PyPI with official dependencies and py-multicodec>=2.0.0 for base58

---

Critical Path Summary

1. py-multihash 3.0.0 (add type annotations) → PyPI ✅ DONE
   ↓ (required by py-cid)
2. py-multibase 2.0.0 (new release required) → PyPI (required) ✅ DONE
3. py-multicodec 2.0.0 (new release with base58 integration) → PyPI (required)
4. py-cid 0.4.0 (migrate to py-multihash>=3.0.0 AND base58 to py-multicodec>=2.0.0) → PyPI
   ↓ (required by py-libp2p via multiaddr)
5. py-libp2p 0.4.1 (switch from fork to official AND base58 to py-multicodec>=2.0.0) → PyPI

Note: Both py-multibase and py-multicodec require new releases. They are independent of py-multihash and can be updated in parallel. py-multicodec 2.0.0 includes base58 functionality, eliminating need for separate base58 package.

Success Criteria

• py-multihash 3.0.0 on PyPI with type annotations ✅ DONE
• py-multibase 2.0.0 on PyPI ✅ DONE
• py-multicodec 2.0.0 on PyPI with base58 integration
• py-cid 0.4.0 on PyPI migrated from base58 to py-multicodec>=2.0.0
• py-libp2p 0.4.1 on PyPI migrated from base58 to py-multicodec>=2.0.0
• py-cid 0.4.0 on PyPI using official py-multihash
• py-libp2p 0.4.1 on PyPI using official py-multihash (no fork)
• All type checking passes (mypy/pyrefly)
• All tests pass
• All base58 functionality works with py-multicodec implementation
• No breaking changes for end users
• Documentation updated

Notes

Base58 Migration

• py-multicodec 2.0.0 provides base58 functionality (replaces standalone base58 package)
• py-cid uses base58 for CIDv0 encoding (via py-multicodec>=2.0.0)
• py-libp2p uses base58 for peer ID encoding (via py-multicodec>=2.0.0)
• Migration completed in fix/multicodec-base58-dep branch for py-libp2p
• API: from multicodec import b58encode, b58decode
• Functions maintain compatibility: b58encode(data: bytes) -> bytes, b58decode(encoded: str) -> bytes

Version Changes

• py-multicodec: Changed from 1.0.0 to 2.0.0 (major version bump due to base58 integration)
• This is a significant feature addition that warrants a major version bump

Timing

• py-multicodec 2.0.0 must be released before py-cid 0.4.0 and py-libp2p 0.4.1
• Both py-cid and py-libp2p depend on py-multicodec>=2.0.0 for base58 functionality

References

• Migration documentation: downloads/base58-to-multicodec-migration.md
• Current pyproject.toml: Shows py-multicodec>=2.0.0 dependency
• Branch: fix/multicodec-base58-dep (contains completed migration for py-libp2p)

Additional Considerations

• Consider a beta/rc release for py-libp2p 0.4.1 to test with community
• Test base58 functionality thoroughly in both py-cid and py-libp2p
• Verify backward compatibility of base58 encoding/decoding

[acul71]

New release plan has been done.