sal/PUBLISHING.md

SAL Publishing Guide

This guide explains how to publish SAL crates to crates.io and how users can consume them.

🎯 Publishing Strategy

SAL uses a modular publishing approach where each module is published as an individual crate. This allows users to install only the functionality they need, reducing compilation time and binary size.

📦 Crate Structure

Individual Crates

Each SAL module is published as a separate crate:

Crate Name	Description	Category
sal-os	Operating system operations	Core
sal-process	Process management	Core
sal-text	Text processing utilities	Core
sal-net	Network operations	Core
sal-git	Git repository management	Infrastructure
sal-vault	Cryptographic operations	Infrastructure
sal-kubernetes	Kubernetes cluster management	Infrastructure
sal-virt	Virtualization tools (Buildah, nerdctl)	Infrastructure
sal-redisclient	Redis database client	Clients
sal-postgresclient	PostgreSQL database client	Clients
sal-zinit-client	Zinit process supervisor client	Clients
sal-mycelium	Mycelium network client	Clients
sal-rhai	Rhai scripting integration	Scripting

Meta-crate

The main sal crate serves as a meta-crate that re-exports all modules with optional features:

[dependencies]
sal = { version = "0.1.0", features = ["os", "process", "text"] }

🚀 Publishing Process

Prerequisites

1. Crates.io Account: Ensure you have a crates.io account and API token
2. Repository Access: Ensure the repository URL is accessible
3. Version Consistency: All crates should use the same version number

Publishing Individual Crates

Each crate can be published independently:

# Publish core modules
cd os && cargo publish
cd ../process && cargo publish
cd ../text && cargo publish
cd ../net && cargo publish

# Publish infrastructure modules
cd ../git && cargo publish
cd ../vault && cargo publish
cd ../kubernetes && cargo publish
cd ../virt && cargo publish

# Publish client modules
cd ../redisclient && cargo publish
cd ../postgresclient && cargo publish
cd ../zinit_client && cargo publish
cd ../mycelium && cargo publish

# Publish scripting module
cd ../rhai && cargo publish

# Finally, publish the meta-crate
cd .. && cargo publish

Automated Publishing

Use the comprehensive publishing script:

# Test the publishing process (safe)
./scripts/publish-all.sh --dry-run --version 0.1.0

# Actually publish to crates.io
./scripts/publish-all.sh --version 0.1.0

The script handles:

• ✅ Dependency order - Publishes crates in correct dependency order
• ✅ Path dependencies - Automatically updates path deps to version deps
• ✅ Rate limiting - Waits between publishes to avoid rate limits
• ✅ Error handling - Stops on failures with clear error messages
• ✅ Dry run mode - Test without actually publishing

👥 User Consumption

Installation Options

Option 1: Individual Crates (Recommended)

Users install only what they need:

# Core functionality
cargo add sal-os sal-process sal-text sal-net

# Database operations
cargo add sal-redisclient sal-postgresclient

# Infrastructure management
cargo add sal-git sal-vault sal-kubernetes

# Service integration
cargo add sal-zinit-client sal-mycelium

# Scripting
cargo add sal-rhai

Usage:

use sal_os::fs;
use sal_process::run;
use sal_git::GitManager;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let files = fs::list_files(".")?;
    let result = run::command("echo hello")?;
    let git = GitManager::new(".")?;
    Ok(())
}

Option 2: Meta-crate with Features

Users can use the main crate with selective features:

# Specific modules
cargo add sal --features os,process,text

# Feature groups
cargo add sal --features core              # os, process, text, net
cargo add sal --features clients           # redisclient, postgresclient, zinit_client, mycelium
cargo add sal --features infrastructure    # git, vault, kubernetes, virt
cargo add sal --features scripting         # rhai

# Everything
cargo add sal --features all

Usage:

// Cargo.toml: sal = { version = "0.1.0", features = ["os", "process", "git"] }
use sal::os::fs;
use sal::process::run;
use sal::git::GitManager;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let files = fs::list_files(".")?;
    let result = run::command("echo hello")?;
    let git = GitManager::new(".")?;
    Ok(())
}

Feature Groups

The meta-crate provides convenient feature groups:

• core: Essential system operations (os, process, text, net)
• clients: Database and service clients (redisclient, postgresclient, zinit_client, mycelium)
• infrastructure: Infrastructure management tools (git, vault, kubernetes, virt)
• scripting: Rhai scripting support (rhai)
• all: Everything included

📋 Version Management

Semantic Versioning

All SAL crates follow semantic versioning:

• Major version: Breaking API changes
• Minor version: New features, backward compatible
• Patch version: Bug fixes, backward compatible

Synchronized Releases

All crates are released with the same version number to ensure compatibility:

# All crates use the same version
sal-os = "0.1.0"
sal-process = "0.1.0"
sal-git = "0.1.0"
# etc.

🔧 Maintenance

Updating Dependencies

When updating dependencies:

1. Update Cargo.toml in the workspace root
2. Update individual crate dependencies if needed
3. Test all crates: cargo test --workspace
4. Publish with incremented version numbers

Adding New Modules

To add a new SAL module:

1. Create the new crate directory
2. Add to workspace members in root Cargo.toml
3. Add optional dependency in root Cargo.toml
4. Add feature flag in root Cargo.toml
5. Add conditional re-export in src/lib.rs
6. Update documentation

🎉 Benefits

For Users

• Minimal Dependencies: Install only what you need
• Faster Builds: Smaller dependency trees compile faster
• Smaller Binaries: Reduced binary size
• Clear Dependencies: Explicit about what functionality is used

For Maintainers

• Independent Releases: Can release individual crates as needed
• Focused Testing: Test individual modules in isolation
• Clear Ownership: Each crate has clear responsibility
• Easier Maintenance: Smaller, focused codebases

This publishing strategy provides the best of both worlds: modularity for users who want minimal dependencies, and convenience for users who prefer a single crate with features.