finish/PUBLISHING.md

# Publishing Guide for finish.sh

This guide explains how to publish and distribute finish.sh through various channels.

## Overview

finish.sh can be distributed through multiple channels:
1. **Direct installation script** - One-line curl install
2. **Debian/Ubuntu packages** - APT repository
3. **Homebrew** - macOS package manager
4. **Docker** - Container images
5. **GitHub Releases** - Direct downloads

## Prerequisites

Before publishing, ensure:
- [ ] All tests pass (`./run_tests.sh`)
- [ ] Version numbers are updated in all files
- [ ] CHANGELOG.md is updated
- [ ] Documentation is complete and accurate

## Version Management

Update version numbers in these files:
1. `finish.sh` - Line 34: `export ACSH_VERSION=0.5.0`
2. `debian/changelog` - Add new entry
3. `homebrew/finish.rb` - Line 6: `version "0.5.0"`
4. `docs/install.sh` - Line 7: `ACSH_VERSION="v0.5.0"`
5. `Dockerfile` - Line 6: `LABEL version="0.5.0"`

## 1. Direct Installation Script

The install script at `docs/install.sh` enables one-line installation:

```bash
curl -sSL https://git.appmodel.nl/Tour/finish/raw/branch/main/docs/install.sh | bash
```

### Setup:
- Host the script on a reliable server or GitHub/GitLab
- Ensure the URL is accessible and supports HTTPS
- Test the installation on clean systems

### Testing:
```bash
# Test in Docker
docker run --rm -it ubuntu:22.04 bash
curl -sSL YOUR_URL/install.sh | bash
```

## 2. Debian/Ubuntu Packages

### Building the Package

```bash
# Install build tools
sudo apt-get install debhelper devscripts

# Build the package
dpkg-buildpackage -us -uc -b

# This creates:
# ../finish_0.5.0-1_all.deb
```

### Testing the Package

```bash
# Install locally
sudo dpkg -i ../finish_*.deb
sudo apt-get install -f  # Fix dependencies

# Test installation
finish --help
finish install
```

### Creating an APT Repository

#### Option A: Using Packagecloud (Recommended for beginners)

1. Sign up at https://packagecloud.io
2. Create a repository
3. Upload your .deb file:
   ```bash
   gem install package_cloud
   package_cloud push yourname/finish/ubuntu/jammy ../finish_*.deb
   ```

Users install with:
```bash
curl -s https://packagecloud.io/install/repositories/yourname/finish/script.deb.sh | sudo bash
sudo apt-get install finish
```

#### Option B: Using GitHub Pages + reprepro

1. Create a repository structure:
   ```bash
   mkdir -p apt-repo/{conf,pool,dists}
   ```

2. Create `apt-repo/conf/distributions`:
   ```
   Origin: finish.sh
   Label: finish
   Codename: stable
   Architectures: all
   Components: main
   Description: APT repository for finish.sh
   ```

3. Add packages:
   ```bash
   reprepro -b apt-repo includedeb stable ../finish_*.deb
   ```

4. Host on GitHub Pages or your server

Users install with:
```bash
echo "deb https://your-domain.com/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/finish.list
curl -fsSL https://your-domain.com/apt-repo/key.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install finish
```

## 3. Homebrew Formula

### Creating a Homebrew Tap

1. Create a GitHub repository: `homebrew-finish`

2. Add the formula to `Formula/finish.rb`

3. Create a release tarball and calculate SHA256:
   ```bash
   git archive --format=tar.gz --prefix=finish-0.5.0/ v0.5.0 > finish-0.5.0.tar.gz
   sha256sum finish-0.5.0.tar.gz
   ```

4. Update the formula with the correct URL and SHA256

5. Test the formula:
   ```bash
   brew install --build-from-source ./homebrew/finish.rb
   brew test finish
   brew audit --strict finish
   ```

### Publishing the Tap

Users can install with:
```bash
brew tap yourname/finish
brew install finish
```

Or directly:
```bash
brew install yourname/finish/finish
```

## 4. Docker Images

### Building Images

```bash
# Production image
docker build -t finish:0.5.0 -t finish:latest .

# Test image
docker build -f Dockerfile.test -t finish:test .
```

### Publishing to GitHub Container Registry

The GitHub Actions workflow automatically publishes Docker images when you push a tag:

```bash
git tag -a v0.5.0 -m "Release v0.5.0"
git push origin v0.5.0
```

Images will be available at:
```
ghcr.io/appmodel/finish:0.5.0
ghcr.io/appmodel/finish:latest
```

### Publishing to Docker Hub

```bash
# Login
docker login

# Tag and push
docker tag finish:latest yourname/finish:0.5.0
docker tag finish:latest yourname/finish:latest
docker push yourname/finish:0.5.0
docker push yourname/finish:latest
```

## 5. GitHub Releases

### Automated Release Process

The `.github/workflows/release.yml` workflow automatically:
1. Creates release artifacts when you push a tag
2. Builds Debian packages
3. Publishes Docker images
4. Creates a GitHub release with downloads

### Manual Release Process

1. Create a release tarball:
   ```bash
   git archive --format=tar.gz --prefix=finish-0.5.0/ v0.5.0 > finish-0.5.0.tar.gz
   ```

2. Create release on GitHub:
   - Go to Releases → Draft a new release
   - Tag: `v0.5.0`
   - Title: `finish.sh v0.5.0`
   - Upload: tarball and .deb file
   - Write release notes

## Release Checklist

Before releasing a new version:

- [ ] Update all version numbers
- [ ] Update CHANGELOG.md
- [ ] Run all tests
- [ ] Test installation script
- [ ] Build and test Debian package
- [ ] Test Docker images
- [ ] Update documentation
- [ ] Create git tag
- [ ] Push tag to trigger CI/CD
- [ ] Verify GitHub release created
- [ ] Verify Docker images published
- [ ] Update Homebrew formula with new SHA256
- [ ] Test installation from all sources
- [ ] Announce release (if applicable)

## Distribution URLs

After publishing, users can install from:

**Quick Install:**
```bash
curl -sSL https://git.appmodel.nl/Tour/finish/raw/branch/main/docs/install.sh | bash
```

**Homebrew:**
```bash
brew tap appmodel/finish
brew install finish
```

**APT (if configured):**
```bash
sudo apt-get install finish
```

**Docker:**
```bash
docker pull ghcr.io/appmodel/finish:latest
```

**Direct Download:**
```
https://git.appmodel.nl/Tour/finish/releases/latest
```

## Troubleshooting

### Debian Package Issues

**Problem:** Package won't install
```bash
# Check dependencies
dpkg-deb -I finish_*.deb
# Test installation
sudo dpkg -i finish_*.deb
sudo apt-get install -f
```

**Problem:** Lintian warnings
```bash
lintian finish_*.deb
# Fix issues in debian/ files
```

### Homebrew Issues

**Problem:** Formula audit fails
```bash
brew audit --strict ./homebrew/finish.rb
# Fix issues reported
```

**Problem:** Installation fails
```bash
brew install --verbose --debug ./homebrew/finish.rb
```

### Docker Issues

**Problem:** Build fails
```bash
docker build --no-cache -t finish:test .
```

**Problem:** Image too large
```bash
# Use multi-stage builds
# Remove unnecessary files
# Combine RUN commands
```

## Continuous Integration

The project includes three GitHub Actions workflows:

1. **test.yml** - Runs on every push/PR
   - Runs BATS tests
   - Tests installation
   - Runs shellcheck
   - Tests Docker builds

2. **docker.yml** - Builds and publishes Docker images
   - Triggered by tags and main branch
   - Publishes to GitHub Container Registry

3. **release.yml** - Creates releases
   - Triggered by version tags
   - Builds all artifacts
   - Creates GitHub release
   - Publishes packages

## Support and Documentation

- Update the README.md with installation instructions
- Maintain CHANGELOG.md with version history
- Create issue templates for bug reports and feature requests
- Set up discussions for community support

## Security Considerations

- Always use HTTPS for installation scripts
- Sign Debian packages with GPG
- Use checksums for release artifacts
- Regularly update dependencies
- Monitor for security vulnerabilities

## Next Steps

After initial publication:
1. Monitor GitHub issues for user feedback
2. Set up analytics if desired
3. Create documentation site
4. Announce on relevant forums/communities
5. Consider submitting to package manager directories