finish/PUBLISHING.md

Publishing Guide for inish .sh

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

Overview

inish .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. inish .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:

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:

# 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

# 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

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

   gem install package_cloud
   package_cloud push yourname/finish/ubuntu/jammy ../finish_*.deb
   

Users install with:

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:

   mkdir -p apt-repo/{conf,pool,dists}
   

2. Create apt-repo/conf/distributions:

   Origin: inish .sh
   Label: finish
   Codename: stable
   Architectures: all
   Components: main
   Description: APT repository for inish .sh
   

3. Add packages:

   reprepro -b apt-repo includedeb stable ../finish_*.deb
   

4. Host on GitHub Pages or your server

Users install with:

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:

   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:

   brew install --build-from-source ./homebrew/finish.rb
   brew test finish
   brew audit --strict finish
   

Publishing the Tap

Users can install with:

brew tap yourname/finish
brew install finish

Or directly:

brew install yourname/finish/finish

4. Docker Images

Building Images

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

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

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

   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: inish .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:

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

Homebrew:

brew tap appmodel/finish
brew install finish

APT (if configured):

sudo apt-get install finish

Docker:

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

# Check dependencies
dpkg-deb -I finish_*.deb
# Test installation
sudo dpkg -i finish_*.deb
sudo apt-get install -f

Problem: Lintian warnings

lintian finish_*.deb
# Fix issues in debian/ files

Homebrew Issues

Problem: Formula audit fails

brew audit --strict ./homebrew/finish.rb
# Fix issues reported

Problem: Installation fails

brew install --verbose --debug ./homebrew/finish.rb

Docker Issues

Problem: Build fails

docker build --no-cache -t finish:test .

Problem: Image too large

# 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