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:

```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<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:

```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<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:

```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.