HUMΛN

Protocol Evolution

HUMΛN evolves through community-driven improvement proposals while maintaining stability, backward compatibility, and security. Protocol evolution is deliberate, transparent, and inclusive.

Semantic Versioning

HUMΛN follows semantic versioning (MAJOR.MINOR.PATCH) to communicate the scope of changes:

MAJOR (e.g., 1.0.0 → 2.0.0)

Breaking changes that require code updates. Announced 6+ months in advance with migration guides.

Example: New Passport cryptographic format

MINOR (e.g., 1.0.0 → 1.1.0)

New features and capabilities added in a backward-compatible way. Existing code continues to work.

Example: New delegation constraint types

PATCH (e.g., 1.0.0 → 1.0.1)

Bug fixes and performance improvements. No feature changes or API updates.

Example: Fixed edge case in capability verification

Release Cadence

Release TypeFrequencyNotice Period
PATCHAs needed (1-2 weeks)1 week
MINORQuarterly4 weeks
MAJORYearly (or as needed)6 months

Backward Compatibility Guarantee

Stability Promise

HUMΛN guarantees backward compatibility within major versions. Code written for v1.0 will work on v1.9 without modifications.

✅ Version Negotiation

Clients specify their protocol version. The server responds with features available at that version.

python
# Client specifies version
client = HumanClient(
    api_key="...",
    protocol_version="1.5"
)


# Server responds with compatible features
info = client.system.info()
print(f"Server version: {info.version}")
print(f"Compatible with: {info.compatible_versions}")

✅ Feature Detection

Check for feature availability before using new capabilities.

python
# Check if feature exists
if client.features.supports("delegation_time_restrictions"):
    # Use new feature
    delegation = client.delegation.create(
        ...,
        constraints={"time_restrictions": {...}}
    )
else:
    # Fallback for older versions
    delegation = client.delegation.create(...)

Deprecation Policy

When features must be removed or changed, we follow a deliberate deprecation process:

Phase 1: Announcement (Release N)

Feature marked as deprecated in documentation and SDK. Runtime warnings added.

Phase 2: Migration (Release N+1)

Migration guides published. Alternative features available. Warnings become more prominent.

Phase 3: Removal (Release N+2)

Feature removed in next major version. Minimum 1 year between announcement and removal.

python
# SDK shows deprecation warnings
import warnings


@deprecated(
    version="1.5.0",
    replacement="client.capability.grant",
    removal_version="2.0.0"
)
def grant_capability_legacy(...):
    warnings.warn(
        "grant_capability_legacy is deprecated. "
        "Use client.capability.grant instead. "
        "Will be removed in v2.0.0",
        DeprecationWarning
    )

Testing & Validation

Before any release, changes go through rigorous testing:

Unit & Integration Tests

>95% code coverage. All edge cases tested.

Compatibility Tests

Backward compatibility verified against all supported versions.

Beta Testing

Community members test releases on staging environments.

Security Audits

Major releases audited by third-party security firms.

Emergency Updates

Critical Security Patches

In the event of a critical security vulnerability, emergency patches may be released outside the normal cadence. These are announced immediately with upgrade instructions.

Subscribe to security notifications:

https://human.dev/security/subscribe

Upgrade Guide

python
# Check current version
client = HumanClient(api_key="...")
info = client.system.info()
print(f"Current: {info.version}")


# Check for updates
updates = client.system.check_updates()
if updates.available:
    print(f"New version: {updates.latest_version}")
    print(f"Breaking changes: {updates.breaking_changes}")
    print(f"Migration guide: {updates.migration_url}")


# Test against new version (staging)
staging_client = HumanClient(
    api_key="...",
    base_url="https://staging-v2.human.dev"
)


# Run your test suite
run_integration_tests(staging_client)


# If tests pass, upgrade production
# pip install --upgrade human-sdk

Related

Community Governance

How proposals are approved

Changelog

See all protocol releases