TypeDialog/docs/RELEASE.md

<div align="center">
  <img src="../imgs/typedialog_logo_h_s.svg" alt="TypeDialog Logo" width="600" />
</div>

# Release Workflow

Guide for preparing and publishing TypeDialog releases.

## Release Stages

Complete release workflow has 4 stages:

1. **Build** - Compile binaries (see [BUILD.md](BUILD.md))
2. **Package** - Create distribution archives
3. **Prepare** - Generate checksums and release notes
4. **Publish** - Upload to GitHub

## Stage 1: Build Binaries

See [BUILD.md](BUILD.md#building-binaries) for complete build instructions.

Quick reference:

```bash
# Build release binaries
just distro::build-release

# Or cross-compile all platforms
just distro::cross
```

**Output**: Binaries in `target/release/`

## Stage 2: Create Distribution Package

Package includes binaries, configs, and installers:

```bash
# Create distribution
just distro::create-package
```

**Output:** `distribution/typedialog-0.1.0/`

Contains:
- `bin/` - Compiled binaries
- `config/` - Configuration templates
- `installers/` - Installation scripts
- `MANIFEST.json` - Package metadata

See [BUILD.md](BUILD.md#distribution-structure) for details.

## Stage 3: Prepare Release

Generate checksums and release notes:

```bash
# Generate checksums
just distro::create-checksums

# Prepare release
just distro::package-release
```

**Output:** `release/`

```
release/
├── typedialog-0.1.0.tar.gz      # Distribution package
├── SHA256SUMS                     # Checksums
└── RELEASE_NOTES.md               # Release documentation
```

### Checksums

Verify package integrity:

```bash
# On your machine
sha256sum -c SHA256SUMS

# For users
sha256sum typedialog-0.1.0.tar.gz
# Compare with SHA256SUMS
```

### Release Notes

Auto-generated with:
- Installation instructions (all platforms)
- Verification steps
- Contents summary
- Platform support matrix

Edit `release/RELEASE_NOTES.md` if needed:
```bash
nano release/RELEASE_NOTES.md
```

## Stage 4: GitHub Release

### Create Release with GitHub CLI

```bash
# Create release
gh release create v0.1.0 \
    release/typedialog-0.1.0.tar.gz \
    release/SHA256SUMS \
    --title "TypeDialog 0.1.0" \
    --notes-file release/RELEASE_NOTES.md
```

### Create Release via Web UI

1. Go to [GitHub Releases](https://github.com/anthropics/typedialog/releases)
2. Click "Draft a new release"
3. Fill in:
   - **Tag version**: `v0.1.0`
   - **Release title**: `TypeDialog 0.1.0`
   - **Description**: Copy from `release/RELEASE_NOTES.md`
4. Upload files:
   - `release/typedialog-0.1.0.tar.gz`
   - `release/SHA256SUMS`
5. Publish

## Complete Release Example

Step-by-step release process:

```bash
# 1. Update version in Cargo.toml
nano crates/typedialog-core/Cargo.toml
# Change version = "0.1.0" to new version

# 2. Commit version change
git add crates/typedialog-core/Cargo.toml
git commit -m "chore: bump version to 0.1.0"

# 3. Run full CI/CD
just ci-full

# 4. Build and package
just distro::build-release
just distro::create-package
just distro::create-checksums

# 5. Prepare release
just distro::package-release

# 6. Verify contents
just distro::list-packages

# 7. Review release notes
cat release/RELEASE_NOTES.md

# 8. Create git tag
git tag -a v0.1.0 -m "Release 0.1.0"
git push origin v0.1.0

# 9. Create GitHub release
gh release create v0.1.0 \
    release/typedialog-0.1.0.tar.gz \
    release/SHA256SUMS \
    --title "TypeDialog 0.1.0" \
    --notes-file release/RELEASE_NOTES.md

# 10. Verify installation works
curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash
typedialog --version
```

## Installation Verification

After release, verify installation methods work:

### Linux/macOS

```bash
# Download and run installer
curl -fsSL https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.sh | bash

# Verify
typedialog --version
typedialog-tui --version
typedialog-web --version
```

### Windows PowerShell

```powershell
# Download and run installer
irm https://github.com/anthropics/typedialog/releases/download/v0.1.0/install.ps1 | iex

# Verify
typedialog --version
typedialog-tui --version
typedialog-web --version
```

### Manual Installation

```bash
# Extract distribution
tar -xzf typedialog-0.1.0.tar.gz
cd typedialog-0.1.0

# Install
bash installers/install.sh

# Verify
typedialog --version
```

## Distribution Structure

### Inside typedialog-0.1.0.tar.gz

```
typedialog-0.1.0/
├── bin/
│   ├── typedialog        # CLI binary
│   ├── typedialog-tui    # TUI binary
│   └── typedialog-web    # Web binary
├── config/
│   ├── cli/
│   │   ├── default.toml
│   │   ├── dev.toml
│   │   └── production.toml
│   ├── tui/
│   │   ├── default.toml
│   │   ├── dev.toml
│   │   └── production.toml
│   └── web/
│       ├── default.toml
│       ├── dev.toml
│       └── production.toml
├── installers/
│   ├── install.sh         # Linux/macOS
│   ├── install.ps1        # Windows
│   └── README.md          # Instructions
└── MANIFEST.json          # Metadata
```

### MANIFEST.json

Package metadata with structure and contents:

```json
{
  "name": "typedialog",
  "version": "0.1.0",
  "created": "2024-12-17T12:00:00Z",
  "structure": {...},
  "binaries": [...],
  "configs": {...},
  "installers": {...}
}
```

## Security Considerations

### Checksums

Always provide checksums:
```bash
sha256sum typedialog-0.1.0.tar.gz > SHA256SUMS
```

Users verify with:
```bash
sha256sum -c SHA256SUMS
```

### Installation Scripts

Review before releasing:
```bash
# Linux/macOS
less installers/bootstrap/install.sh

# Windows
less installers/bootstrap/install.ps1
```

### Production Configurations

Verify security settings in production configs:

```toml
# config/web/production.toml
[security]
require_https = true
csrf_enabled = true
rate_limit = 100
add_security_headers = true
```

See [CONFIGURATION.md](CONFIGURATION.md) for all settings.

## Continuous Integration

### GitHub Actions

Example CI workflow for automated releases:

```yaml
# .github/workflows/release.yml
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: rust-lang/rust-action@v1

      - name: Build release
        run: just distro::build-release

      - name: Create package
        run: just distro::create-package

      - name: Generate checksums
        run: just distro::create-checksums

      - name: Prepare release
        run: just distro::package-release

      - name: Create GitHub release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/typedialog-*.tar.gz
            release/SHA256SUMS
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Troubleshooting

### Release file not found

Ensure files exist in `release/`:
```bash
just distro::list-packages
ls -la release/
```

### Checksum mismatch

Regenerate checksums:
```bash
just distro::create-checksums
```

### Installation script fails

Test locally:
```bash
# macOS/Linux
bash installers/bootstrap/install.sh

# Windows
pwsh installers/bootstrap/install.ps1
```

### GitHub release failed

Check permissions:
```bash
gh auth status
gh release list
```

## Release Checklist

Before releasing:

- [ ] Version updated in `crates/typedialog-core/Cargo.toml`
- [ ] All tests passing: `just ci::full`
- [ ] Binaries built: `just distro::build-release`
- [ ] Package created: `just distro::create-package`
- [ ] Checksums verified: `just distro::create-checksums`
- [ ] Release notes generated: `just distro::package-release`
- [ ] Installation tested (at least one platform)
- [ ] GitHub tag created: `git tag v0.1.0`
- [ ] Release published to GitHub
- [ ] Documentation updated

## Release Notes Template

When editing `release/RELEASE_NOTES.md`:

```markdown
# TypeDialog 0.1.0

## What's New

- Feature 1
- Feature 2
- Bug fix 1

## Installation

### Linux/macOS
\`\`\`bash
curl -fsSL https://github.com/.../install.sh | bash
\`\`\`

### Windows
\`\`\`powershell
irm https://github.com/.../install.ps1 | iex
\`\`\`

## Verification

\`\`\`bash
sha256sum -c SHA256SUMS
\`\`\`

## Downloads

- typedialog-0.1.0.tar.gz
- SHA256SUMS

## Platforms

- Linux x86_64, ARM64
- macOS Intel, Apple Silicon
- Windows x86_64
```

## Next Steps

- [BUILD.md](BUILD.md) - Building binaries
- [CONFIGURATION.md](CONFIGURATION.md) - Configuration options
- [INSTALLATION.md](INSTALLATION.md) - User installation guide

---

**Release complete!** 🎉

Users can now install via automated installers.