kportal/RELEASE_SETUP.md

Release Infrastructure Setup Summary

This document summarizes all the release infrastructure that has been set up for kportal.

✅ Completed Setup

1. GitHub Actions CI/CD Pipeline

File: .github/workflows/release.yml

Features:

• Multi-platform binary builds (Linux, macOS, Windows - amd64 & arm64)
• Automatic release creation on version tags
• Binary archiving (tar.gz for Unix, zip for Windows)
• SHA256 checksum generation
• Automated Homebrew formula updates
• Release notes generation

How to trigger:

# Commit with semantic versioning keywords
git commit -m "feat: add new feature"

# Tag the release
git tag -a v0.2.0 -m "Release v0.2.0"

# Push tags
git push origin v0.2.0

The pipeline will automatically:

1. Build binaries for all platforms
2. Create GitHub release with binaries
3. Update Homebrew tap formula
4. Generate release notes

2. Installation Methods

A. Homebrew Formula

File: Formula/kportal.rb

Installation command:

brew install lukaszraczylo/tap/kportal

Note: Formula is automatically updated by CI/CD pipeline. You'll need to create a separate tap repository:

1. Create repo: https://github.com/lukaszraczylo/brew-taps
2. Add Formula/kportal.rb to that repo
3. Set HOMEBREW_TAP_TOKEN secret in GitHub repository settings

B. Quick Install Script

File: install.sh

Features:

• Auto-detects OS and architecture
• Downloads appropriate binary
• Extracts and installs to /usr/local/bin
• Verifies installation
• Colorful output with emoji indicators

Installation command:

curl -fsSL https://raw.githubusercontent.com/lukaszraczylo/kportal/main/install.sh | bash

C. Manual Download

Users can download binaries directly from GitHub releases:

https://github.com/lukaszraczylo/kportal/releases

3. Documentation

A. Comprehensive README.md

File: README.md

Contents:

• Feature showcase with emojis
• Multiple installation methods
• Quick start guide
• Configuration examples
• Usage instructions
• Advanced features documentation
• Troubleshooting guide
• Contributing guidelines

B. GitHub Pages Website

File: docs/index.html

Features:

• Modern, responsive design with TailwindCSS
• Hero section with clear CTA
• Feature showcase cards
• Installation guide
• Configuration examples with syntax highlighting
• Documentation links
• Mobile-friendly

URL (once enabled): https://lukaszraczylo.github.io/kportal

To enable:

1. Go to GitHub repository settings
2. Pages section
3. Source: Deploy from a branch
4. Branch: main
5. Folder: /docs

4. Supporting Files

CHANGELOG.md

File: CHANGELOG.md

Tracks all changes following Keep a Changelog format. Update this file with each release.

CONTRIBUTING.md

File: CONTRIBUTING.md

Guidelines for:

• Bug reporting
• Feature requests
• Pull request process
• Commit message format
• Development setup
• Testing guidelines

🚀 Release Workflow

Standard Release Process

1. Develop features

   git checkout -b feature/my-feature
   # Make changes
   make test
   make all
   

2. Commit with semantic messages

   git commit -m "feat: add amazing feature"
   git commit -m "fix: resolve bug in health check"
   

3. Update CHANGELOG.md

   ## [0.2.0] - 2025-11-24
   
   ### Added
   - Amazing new feature
   
   ### Fixed
   - Bug in health check
   

4. Tag the release

   git tag -a v0.2.0 -m "Release v0.2.0"
   git push origin main
   git push origin v0.2.0
   

5. CI/CD automatically:

   • Builds all binaries
   • Creates GitHub release
   • Updates Homebrew formula
   • Attaches binaries and checksums

Version Bumping (Semantic Versioning)

Version is automatically determined by semver-gen from commit messages:

• Patch (0.0.X): fix, bugfix, hotfix, patch, docs, test, refactor
• Minor (0.X.0): feat, feature, add, enhance, update, improve
• Major (X.0.0): breaking, major, BREAKING CHANGE

📦 Platform Support

Supported Platforms

OS	Architecture	Archive Format
Linux	amd64	tar.gz
Linux	arm64	tar.gz
macOS	amd64	tar.gz
macOS	arm64	tar.gz
Windows	amd64	zip
Windows	arm64	zip

🔒 Required GitHub Secrets

For full automation, set these secrets in your GitHub repository:

1. GITHUB_TOKEN - Automatically provided by GitHub Actions
2. HOMEBREW_TAP_TOKEN - Personal access token for updating Homebrew tap
   • Create at: https://github.com/settings/tokens
   • Permissions needed: repo scope
   • Add to repository secrets

📝 Next Steps

1. Enable GitHub Pages

• Repository Settings → Pages → Source: main branch, /docs folder

2. Create Homebrew Tap Repository

# Create new repository
gh repo create lukaszraczylo/brew-taps --public

# Clone and set up
git clone https://github.com/lukaszraczylo/brew-taps
cd brew-taps
cp ../kportal/Formula/kportal.rb ./Formula/
git add Formula/kportal.rb
git commit -m "Initial formula for kportal"
git push origin main

3. Add GitHub Token to Secrets

• Repository Settings → Secrets and variables → Actions
• New repository secret
• Name: HOMEBREW_TAP_TOKEN
• Value: Your personal access token

4. Create First Release

cd kportal
git add .
git commit -m "feat: initial release setup"
git push origin main
git tag -a v0.1.5 -m "Release v0.1.5"
git push origin v0.1.5

5. Test Installation Methods

After first release, test:

# Homebrew (once tap is set up)
brew install lukaszraczylo/tap/kportal

# Quick install script
curl -fsSL https://raw.githubusercontent.com/lukaszraczylo/kportal/main/install.sh | bash

# Manual download
# Visit releases page and download binary

🎨 Customization

Update Website Colors

Edit docs/index.html:

tailwind.config = {
    theme: {
        extend: {
            colors: {
                primary: '#3b82f6',    // Blue
                secondary: '#8b5cf6',   // Purple
                dark: '#0f172a',        // Dark slate
            }
        }
    }
}

Update Release Notes Template

Edit .github/workflows/release.yml in the "Generate release notes" step.

📊 Monitoring

After releases, monitor:

• GitHub Actions workflow runs
• GitHub Releases page
• Homebrew tap repository commits
• Download statistics on releases page

🐛 Troubleshooting

Release workflow fails

• Check GitHub Actions logs
• Verify all required secrets are set
• Ensure tag follows v\d+.\d+.\d+ format

Homebrew formula not updating

• Verify HOMEBREW_TAP_TOKEN is valid
• Check tap repository permissions
• Review release workflow logs

Install script fails

• Test locally with different OS/arch combinations
• Check release binary naming matches script expectations
• Verify binaries are attached to release

✅ Checklist for First Release

• All code committed and pushed
• GitHub Pages enabled
• Homebrew tap repository created
• HOMEBREW_TAP_TOKEN secret set
• CHANGELOG.md updated
• Version tag created and pushed
• Release workflow completed successfully
• Binaries attached to release
• Homebrew formula updated
• Install script tested
• Documentation website live
• README.md installation links work

---

Documentation last updated: 2025-11-23 Setup completed for: kportal v0.1.5