Macula v0.6.0 Release Summary

View Source

Release Date: 2025-11-15 Status: ✅ Ready for Hex publication

What's in v0.6.0

Breaking Changes

  • Environment Variable Rename: GATEWAY_REALM → MACULA_REALM
    • Consistent naming across all MACULA_* environment variables
    • Applies to both gateway mode and edge peer mode

Documentation Improvements

  • New: Comprehensive Kademlia DHT Architecture documentation
    • Location: docs/KADEMLIA_DHT_ARCHITECTURE.md
    • 380 lines covering XOR metrics, k-buckets, DHT operations, and Macula-specific adaptations

Migration Path

Simple find-and-replace for environment variables:

Before (v0.5.0):

export GATEWAY_REALM=my-app

After (v0.6.0):

export MACULA_REALM=my-app

Elixir/Phoenix runtime.exs:

# Before
System.put_env("GATEWAY_REALM", realm)

# After
System.put_env("MACULA_REALM", realm)

Pre-Release Checklist

✅ Completed

  • [x] Version bumped to 0.6.0 in src/macula.app.src
  • [x] Version bumped to 0.6.0 in rebar.config
  • [x] CHANGELOG.md updated with breaking changes and migration guide
  • [x] All MACULA_REALM references consistent throughout codebase
  • [x] Documentation generated (ex_doc)
  • [x] All tests passing (81 tests, 0 failures)
  • [x] Compilation clean (no warnings)
  • [x] Kademlia DHT documentation added

📋 Next Steps (For User)

  1. Run publication script: ./scripts/publish-to-hex.sh
  2. Verify on hex.pm
  3. Update macula-arcade to use v0.6.0
  4. Test Snake game with new version

Files Changed in v0.6.0

Version Files

  • src/macula.app.src (line 3: version bump)
  • rebar.config (line 68: version bump)

Environment Variable Updates

  • src/macula_sup.erl (line 125: GATEWAY_REALM → MACULA_REALM)
  • entrypoint.sh (lines 11, 17, 27: GATEWAY_REALM → MACULA_REALM)
  • Dockerfile.gateway (line 60: ENV variable)
  • config/sys.config (line 10: comment update)

Documentation

  • docs/QUIC_TLS_GATEWAY_SETUP.md (added MACULA_REALM examples)
  • docs/KADEMLIA_DHT_ARCHITECTURE.md (NEW - 380 lines)
  • docs/NOMENCLATURE_PROPOSAL_CONNECTION_TO_PEER.md (NEW - for v0.7.0)
  • docs/PEER_VS_CONNECTION_ANALYSIS.md (NEW - for v0.7.0)
  • docs/PEER_CONNECTION_SEPARATION_PLAN.md (NEW - for v0.7.0)
  • CHANGELOG.md (v0.6.0 entry added)

Total: 11 files modified, 4 files created

Test Results

Compilation: ✅ Clean (no warnings)
Tests: ✅ 81 tests, 0 failures, 6 cancelled
Documentation: ✅ Generated successfully

The 6 cancelled tests are integration tests requiring external infrastructure (expected behavior).

What's Coming in v0.7.0

Planned: Peer-Connection Separation (4.5 weeks)

Major architectural improvement to separate concerns:

macula_peer (High-Level Mesh API):

  • Pub/sub operations
  • RPC calls
  • Service discovery
  • DHT participation
  • Peer identity management

macula_connection (Low-Level QUIC Transport):

  • QUIC connection lifecycle
  • Stream management
  • Message encoding/decoding
  • Reconnection logic

Benefits:

  • Single Responsibility Principle
  • Better testability
  • Future-proof for alternative transports
  • Clearer API separation

Timeline: 4-5 weeks TDD implementation Documentation: See docs/PEER_CONNECTION_SEPARATION_PLAN.md

Package Metadata

Name: macula Version: 0.6.0 License: Apache-2.0 Description: Macula HTTP/3 Mesh Platform - Complete distributed application framework

Dependencies:

  • quicer: 0.2.15
  • msgpack: 0.8.1
  • gproc: 0.9.1

Links:

Publication Commands

# Run the publish script (handles everything)
./scripts/publish-to-hex.sh

# Or manual steps:
rebar3 hex build
rebar3 hex publish

Post-Publication Verification

After publishing, verify:

  1. Hex.pm: Check version appears at https://hex.pm/packages/macula
  2. Documentation: Verify docs rendered correctly on hex.pm
  3. Download Test: Try installing in a test project
  4. macula-arcade: Update dependency to v0.6.0 and test

Status: ✅ READY FOR PUBLICATION

Run ./scripts/publish-to-hex.sh when ready!