first commit
This commit is contained in:
365
PUBLISHING.md
Normal file
365
PUBLISHING.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Publishing Guide for finishte.sh
|
||||
|
||||
This guide explains how to publish and distribute finishte.sh through various channels.
|
||||
|
||||
## Overview
|
||||
|
||||
finishte.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. `finishte.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
|
||||
finishte --help
|
||||
finishte 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: finishte.sh
|
||||
Label: finish
|
||||
Codename: stable
|
||||
Architectures: all
|
||||
Components: main
|
||||
Description: APT repository for finishte.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: `finishte.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
|
||||
Reference in New Issue
Block a user