Skip to content

PACKAGE_MANAGERS.md

Latest commit

 

History

History
341 lines (244 loc) · 8.62 KB

PACKAGE_MANAGERS.md

File metadata and controls

341 lines (244 loc) · 8.62 KB

Package Manager Distribution Guide

This document explains how to distribute pvetui through various package managers including AUR, Homebrew, Scoop, and traditional package formats (DEB/RPM).

Overview

pvetui is distributed through multiple channels to reach users on different platforms:

  • GitHub Releases: Direct binary downloads for all platforms
  • AUR (Arch User Repository): For Arch Linux and derivatives
  • Homebrew Tap: For macOS and Linux users
  • Scoop Bucket: For Windows users
  • DEB/RPM Packages: Traditional Linux package formats
  • Docker Images: Containerized distribution

Prerequisites

Before setting up package managers, ensure you have:

  • Git installed and configured
  • GitHub CLI installed and authenticated
  • GoReleaser installed (for automated releases)
  • Platform-specific tools (see individual sections below)

Quick Start

Use the orchestration script to manage all package managers:

# Set up all package managers
./scripts/package-managers.sh setup

# Check status
./scripts/package-managers.sh status

# Update all to a specific version
./scripts/package-managers.sh update -v 0.6.0

# Create a complete release
./scripts/package-managers.sh release -v 0.6.0

Or use Makefile targets:

# Set up all package managers
make package-managers-setup

# Check status
make package-managers-status

# Update all to a specific version
make package-managers-update VERSION=v0.6.0

# Create a complete release
make package-managers-release VERSION=v0.6.0

AUR (Arch User Repository)

What is AUR?

The Arch User Repository is a community-driven repository for Arch Linux and derivatives. Users can install packages using yay, paru, or makepkg.

Setup

  1. Clone the AUR repository:

    ./scripts/aur-package.sh setup

  2. Update package information:

    ./scripts/aur-package.sh update -v 0.6.0

  3. Build and test locally:

    ./scripts/aur-package.sh build
./scripts/aur-package.sh install

Manual Setup

If you prefer manual setup:

# Clone AUR repository
yay -G pvetui
cd pvetui

# Or clone manually
git clone https://aur.archlinux.org/pvetui.git
cd pvetui

The PKGBUILD file will be created automatically with the correct dependencies and installation paths.

Publishing

  1. Update the PKGBUILD with the new version
  2. Test the package: makepkg -si
  3. Commit and push changes to your AUR repository
  4. Users can install with: yay -S pvetui

Homebrew Tap

What is Homebrew?

Homebrew is a package manager for macOS and Linux. A "tap" is a third-party repository that extends Homebrew's package collection.

Setup

  1. Set up the tap repository:

    ./scripts/homebrew-tap.sh setup

  2. Update formula:

    ./scripts/homebrew-tap.sh update -v 0.6.0

  3. Test locally:

    ./scripts/homebrew-tap.sh test
./scripts/homebrew-tap.sh install

Manual Setup

# Clone tap repository
git clone https://github.com/devnullvoid/homebrew-pvetui.git
cd homebrew-pvetui

# Create Formula directory
mkdir -p Formula

# Create formula file (see scripts/homebrew-tap.sh for template)

Publishing

  1. Update the formula with new version and checksums
  2. Test: brew audit --strict Formula/pvetui.rb
  3. Commit and push changes
  4. Users can install with: brew install devnullvoid/pvetui/pvetui

Scoop Bucket

What is Scoop?

Scoop is a command-line installer for Windows that simplifies the installation of developer tools.

Setup

  1. Set up the bucket repository:

    ./scripts/scoop-bucket.sh setup

  2. Update manifest:

    ./scripts/scoop-bucket.sh update -v 0.6.0

  3. Test locally:

    ./scripts/scoop-bucket.sh test
./scripts/scoop-bucket.sh install

Manual Setup

# Clone bucket repository
git clone https://github.com/devnullvoid/scoop-pvetui.git
cd scoop-pvetui

# Create bucket directory
mkdir -p bucket

# Create manifest file (see scripts/scoop-bucket.sh for template)

Publishing

  1. Update the manifest with new version and checksums
  2. Test: scoop install pvetui
  3. Commit and push changes
  4. Users can install with: scoop bucket add devnullvoid/pvetui && scoop install pvetui

DEB/RPM Packages

What are DEB/RPM?

DEB and RPM are traditional Linux package formats used by Debian/Ubuntu and Red Hat/CentOS respectively.

Setup

These packages are automatically generated by GoReleaser when you create a release. The configuration is in .goreleaser.yaml.

Publishing

  1. Create a git tag: git tag v0.6.0
  2. Push the tag: git push origin v0.6.0
  3. GoReleaser will automatically:
    • Build binaries for all platforms
    • Create DEB and RPM packages
    • Upload to GitHub releases

Docker Images

What are Docker Images?

Docker images provide a containerized way to run pvetui in any environment that supports Docker.

Setup

Docker images are automatically built and published by GoReleaser. The configuration is in .goreleaser.yaml.

Usage

# Pull the latest image
docker pull ghcr.io/devnullvoid/pvetui:latest

# Run the container
docker run -it --rm ghcr.io/devnullvoid/pvetui:latest

# Run with specific version
docker run -it --rm ghcr.io/devnullvoid/pvetui:v0.6.0

Release Workflow

Complete Release Process

  1. Prepare the release:

    # Update CHANGELOG.md
# Commit changes
git add CHANGELOG.md
git commit -m "chore: prepare release v0.6.0"

  2. Create and push tag:

    git tag v0.6.0
git push origin v0.6.0

  3. Automated release (recommended):

    • GitHub Actions will trigger GoReleaser
    • All packages will be built and uploaded
    • Package manager repositories can be updated

  4. Manual package manager updates:

    # Update all package managers
./scripts/package-managers.sh update -v 0.6.0

# Or update individually
./scripts/aur-package.sh update -v 0.6.0
./scripts/homebrew-tap.sh update -v 0.6.0
./scripts/scoop-bucket.sh update -v 0.6.0

Dry Run

Test your release process without making changes:

./scripts/package-managers.sh release -v 0.6.0 -d

Repository Structure

After setup, your workspace will contain:

pvetui/
├── .goreleaser.yaml          # GoReleaser configuration
├── scripts/
│   ├── aur-package.sh        # AUR management script
│   ├── homebrew-tap.sh       # Homebrew tap management
│   ├── scoop-bucket.sh       # Scoop bucket management
│   └── package-managers.sh   # Orchestration script
├── pvetui/              # AUR repository (after setup)
├── homebrew-pvetui/     # Homebrew tap (after setup)
└── scoop-pvetui/        # Scoop bucket (after setup)

Troubleshooting

Common Issues

  1. Missing tools:

    • Install required tools for your platform
    • Use ./scripts/package-managers.sh status to check prerequisites

  2. Authentication issues:

    • Ensure GitHub CLI is authenticated: gh auth login
    • Check repository permissions

  3. Version mismatches:

    • Ensure git tag matches the version you're releasing
    • Use git describe --exact-match --tags HEAD to verify

  4. Package build failures:

    • Check platform-specific requirements
    • Verify binary downloads are accessible
    • Review package manager logs

Getting Help

  • Check the individual script help: ./scripts/aur-package.sh help
  • Review GoReleaser documentation: https://goreleaser.com/
  • Check package manager documentation for your platform

Best Practices

  1. Version consistency: Always use the same version across all package managers
  2. Testing: Test packages locally before publishing
  3. Automation: Use the orchestration scripts to reduce manual errors
  4. Documentation: Keep this guide updated as processes change
  5. Backup: Keep local copies of package manager repositories for quick fixes

Contributing

To improve the package manager setup:

  1. Test changes locally first
  2. Update documentation
  3. Ensure scripts work across different platforms
  4. Add new package managers as needed

References