# Snap Package Release Guide
This document explains how to build and release the rfgrep snap package.
## Overview
The rfgrep snap package is automatically built and released using GitHub Actions workflows. The snap provides a universal package format that works across many Linux distributions.
## Automated Release Process
### GitHub Actions Workflows
1. **Snap Test Build** (`.github/workflows/snap-test.yml`)
- Runs on pushes to main/dev branches and pull requests
- Builds and tests the snap package
- Provides feedback on PRs with test results
- Does not publish to the snap store
2. **Snap Release** (`.github/workflows/snap-release.yml`)
- Runs on git tags (e.g., `v1.0.0`)
- Builds and publishes to the snap store
- Supports manual workflow dispatch for custom releases
### Release Channels
- **edge**: Development releases (prereleases)
- **beta**: Beta releases for testing
- **candidate**: Release candidates
- **stable**: Stable releases
## Manual Release Process
### Prerequisites
1. Install snapcraft:
```bash
sudo snap install snapcraft --classic
```
2. Login to snap store:
```bash
snapcraft login
```
3. Register the snap name (one-time):
```bash
snapcraft register rfgrep
```
### Using the Release Script
The `scripts/release_snap.sh` script automates the manual release process:
```bash
# Build and test only (no publishing)
./scripts/release_snap.sh --build-only
# Dry run (build, test, but don't publish)
./scripts/release_snap.sh --dry-run --version v1.0.0
# Release to edge channel
./scripts/release_snap.sh --channel edge --version v1.0.0
# Release to stable channel
./scripts/release_snap.sh --channel stable --version v1.0.0
```
### Manual Steps
1. **Build the snap:**
```bash
cd snap
snapcraft pack --destructive-mode --output ../rfgrep.snap
```
2. **Test the snap:**
```bash
snap ack rfgrep.snap
snap install rfgrep.snap --dangerous
rfgrep --version
snap remove rfgrep
```
3. **Upload to snap store:**
```bash
snapcraft upload rfgrep.snap --release=edge
```
## Snap Configuration
The snap package is configured in `snap/snapcraft.yaml`:
- **Name**: rfgrep
- **Base**: core22 (Ubuntu 22.04 LTS)
- **Confinement**: strict (sandboxed with specific permissions)
- **Architectures**: amd64, arm64
- **Plugin**: dump (custom build process)
- **Plugs**: home, removable-media, network, network-bind
### Build Process
1. Installs rustup and Rust toolchain
2. Builds the project using `cargo build --release`
3. Copies the binary to the snap package
4. Extracts version from Cargo.toml
## GitHub Secrets
The following secrets need to be configured in the GitHub repository:
- `SNAP_STORE_LOGIN`: Base64-encoded snap store login credentials for `kherld.hussein@gmail.com`
To generate the login credentials:
```bash
# Login to snap store with your account
snapcraft login
# Use email: kherld.hussein@gmail.com
# Use the automated script to generate credentials
./scripts/setup_snap_credentials.sh
# Or manually export credentials
snapcraft export-login snap_login.json
base64 -w 0 snap_login.json
# Add the base64 string as SNAP_STORE_LOGIN secret in GitHub
```
## Testing
### Local Testing
```bash
# Build and test locally
./scripts/release_snap.sh --build-only
# Install and test
snap install rfgrep.snap --dangerous
rfgrep --version
rfgrep --help
snap remove rfgrep
```
### CI Testing
The GitHub Actions workflow automatically:
- Builds the snap package
- Tests basic functionality
- Provides feedback on pull requests
- Uploads test artifacts
## Troubleshooting
### Common Issues
1. **Build fails with LXD errors:**
- Use `--destructive-mode` flag
- Ensure user is in the `lxd` group (if using LXD)
2. **Version not extracted:**
- Check Cargo.toml format
- Ensure version line is properly formatted
3. **Snap store login fails:**
- Verify credentials are correct
- Check if 2FA is enabled (may need app-specific password)
4. **Upload fails:**
- Ensure snap name is registered
- Check if version already exists
- Verify channel permissions
### Debug Commands
```bash
# Check snapcraft version
snapcraft --version
# Check login status
snapcraft whoami
# List registered snaps
snapcraft names
# Check snap package info
snap info rfgrep
```
## Release Checklist
Before releasing a new version:
- [ ] Update version in Cargo.toml
- [ ] Create and push git tag
- [ ] Verify CI tests pass
- [ ] Test snap package locally
- [ ] Check snap store permissions
- [ ] Monitor release workflow
- [ ] Verify installation from snap store
## Installation
Users can install rfgrep from the snap store:
```bash
# Install latest stable
snap install rfgrep
# Install from specific channel
snap install rfgrep --edge
snap install rfgrep --beta
snap install rfgrep --candidate
# Update to latest
snap refresh rfgrep
# Remove
snap remove rfgrep
```
## Links
- [Snap Store Listing](https://snapcraft.io/rfgrep) (Published by kherld.hussein@gmail.com)
- [Snapcraft Documentation](https://snapcraft.io/docs)
- [GitHub Actions Workflows](.github/workflows/)
- [Publisher Account](https://snapcraft.io/account/snaps) (kherld.hussein@gmail.com)