6.3 KiB

Raw Permalink Blame History

ONBOARDING.md — Contributing to Libertaria

From first commit to core contributor

Welcome

You're here because you believe digital sovereignty should be the default, not a privilege. This guide gets you productive in 30 minutes.

Prerequisites

Zig 0.15.2+ — ziglang.org/download
Git — For version control
2+ hours — To read, build, and understand

Optional but helpful:

liboqs — For post-quantum crypto (see vendor/liboqs/)
argon2 — For key derivation (bundled in vendor/argon2/)

5-Minute Setup

# 1. Clone
git clone https://github.com/libertaria-project/libertaria-stack.git
cd libertaria-stack

# 2. Build
zig build

# 3. Test
zig build test

# 4. Run example
zig build examples
./zig-out/bin/lwf_example

Expected: All tests pass, examples run without errors.

Repository Structure

libertaria-stack/
├── core/                    # LCL-1.0 licensed (viral)
│   ├── l0-transport/        # Transport layer
│   ├── l1-identity/         # Identity, crypto, QVL
│   ├── l2_session/          # Session management
│   ├── l2-federation/       # Cross-chain bridging
│   └── l2-membrane/         # Policy enforcement
├── sdk/                     # LSL-1.0 licensed (business-friendly)
│   ├── l4-feed/             # Temporal event store
│   └── janus-sdk/           # Language bindings
├── apps/                    # LUL-1.0 licensed (unbound)
│   └── examples/            # Example applications
├── docs/                    # Specifications and RFCs
│   └── rfcs/                # Request for Comments
└── capsule-core/            # Reference node implementation

Finding Your First Contribution

Good First Issues

Look for issues labeled:

good-first-issue — Self-contained, well-defined
documentation — Typos, clarifications, examples
test-coverage — Add tests for existing code

Areas Needing Help

Area	Skills Needed	Impact
Test Coverage	Zig	High — increase reliability
Documentation	Writing	High — lower barrier to entry
Porting	Rust/Go/TS	Medium — expand ecosystem
Benchmarks	Zig + analysis	Medium — prove performance
Security Review	Crypto expertise	Critical — find vulnerabilities

Development Workflow

1. Fork and Branch

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/libertaria-stack.git
cd libertaria-stack
git checkout -b feature/your-feature-name

2. Make Changes

# Edit code
vim core/l0-transport/noise.zig

# Test your changes
zig test core/l0-transport/noise.zig

# Run full test suite
zig build test

3. Commit

We use Conventional Commits:

# Format: type(scope): description

git commit -m "feat(l0): add QUIC transport skin"
git commit -m "fix(l1): correct QVL path calculation"
git commit -m "docs: clarify SoulKey derivation"
git commit -m "test(l2): add session rotation tests"

Types:

feat — New feature
fix — Bug fix
docs — Documentation only
test — Tests only
refactor — Code change, no behavior change
perf — Performance improvement
chore — Build, tooling, etc.

4. Push and PR

git push origin feature/your-feature-name

Open a PR on GitHub with:

Clear description of what and why
Reference to any related issues
Test results (zig build test output)

Code Standards

Zig Style

// Use explicit types
const count: u32 = 42;

// Error unions, not exceptions
fn mayFail() !Result { ... }

// Defer cleanup
defer allocator.free(buffer);

// Comptime when possible
fn max(comptime T: type, a: T, b: T) T { ... }

Documentation

Every public function needs a doc comment:

/// Derives a deterministic DID from the SoulKey.
/// Context string provides domain separation.
/// Returns error.InvalidContext if context exceeds 64 bytes.
pub fn deriveDid(self: *SoulKey, context: []const u8) !Did { ... }

Testing

test "SoulKey derivation is deterministic" {
    const seed = [_]u8{0x01} ** 32;
    var sk1 = try SoulKey.init(testing.allocator, seed);
    var sk2 = try SoulKey.init(testing.allocator, seed);
    
    const did1 = try sk1.deriveDid("test");
    const did2 = try sk2.deriveDid("test");
    
    try testing.expectEqualStrings(did1, did2);
}

Architecture Decision Records (ADRs)

Major decisions are documented in DECISIONS.md. Before proposing changes that affect:

Protocol design
Cryptographic primitives
API compatibility
Licensing implications

...read existing ADRs and consider writing a new one.

Communication

Where to Ask

GitHub Issues — Bug reports, feature requests
GitHub Discussions — Questions, ideas, RFCs
Moltbook: m/Libertaria — Real-time chat

Code of Conduct

Be direct — German-style honesty over corporate smoothness
Challenge ideas — Not people
Ship beats perfect — Working code > perfect plans
Document everything — Future you will thank present you

Learning Path

Week 1: Understand

Read DIGEST.md (5 min)
Read README.md (30 min)
Build and run tests
Read one RFC (RFC-0015_Transport_Skins.md)

Week 2: Contribute

Fix a typo in documentation
Add a test for existing code
Review a PR

Week 3: Build

Implement a small feature
Write an ADR for a design decision
Help onboard another contributor

Month 2: Lead

Own a component
Mentor new contributors
Propose architectural changes

Recognition

Contributors are recognized in:

CONTRIBUTORS.md (all contributors)
Release notes (significant contributions)
Commit history (permanent)

No CLA required. You keep your copyright.

Questions?

Quick: Check AGENT.md (AI-oriented) or DIGEST.md (human-oriented)
Deep: Read docs/rfcs/
Urgent: Open a GitHub issue
Philosophical: Read blog/libertaria.app

The Bottom Line

We move fast, build correctly, and ship working code. If you're here, you already understand why this matters. Let's build exit infrastructure together.

⚡️

6.3 KiB Raw Permalink Blame History Unescape Escape