# 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: ```toml [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: ```bash # 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: ```bash # 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: ```bash # 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:** ```rust use sal_os::fs; use sal_process::run; use sal_git::GitManager; fn main() -> Result<(), Box> { 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: ```bash # 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:** ```rust // 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> { 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: ```toml # 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.