mirror of
https://github.com/PR0M3TH3AN/VoxVera.git
synced 2026-11-05 14:10:40 +00:00
105 lines
5.0 KiB
Markdown
105 lines
5.0 KiB
Markdown
# VoxVera Release Process
|
|
|
|
**⚠️ ATTENTION AI AGENTS (CRITICAL WORKFLOW):**
|
|
Do **NOT** automatically package, tag, or push a new release after completing a set of changes. Releases should **ONLY** be triggered when the user explicitly requests one (e.g., "Package a release now" or "Let's release this").
|
|
Instead of releasing immediately, you must append a summary of your completed work to the `UPCOMING_RELEASE.md` file. This allows development to span multiple context sessions and ensures that new releases contain a substantial amount of value. When a release is finally requested, use the contents of `UPCOMING_RELEASE.md` to format the GitHub Release notes, and then clear the document for the next cycle.
|
|
|
|
This document outlines the mandatory steps to perform before every release to ensure code quality, cross-language integrity, and professional distribution assets.
|
|
|
|
## 1. Pre-Flight Checks (Quality Assurance)
|
|
|
|
Before any release, the codebase must pass all internal quality checks **without taking any shortcuts**. All tests must be rigorous, use real data where appropriate, and passing them should be a true mark of quality.
|
|
|
|
### Run Tests
|
|
Ensure all core CLI, E2E, and Integrity tests pass:
|
|
```bash
|
|
pytest tests/
|
|
```
|
|
*Note: The `test_integrity.py` check is critical as it verifies that all 14+ language locales have synchronized keys and all binary bundles are 100% self-contained.*
|
|
|
|
### Run Linting
|
|
Ensure the code adheres to style guidelines (no trailing whitespace, proper spacing, etc.):
|
|
```bash
|
|
# Using flake8 (excluding vendored dependencies)
|
|
flake8 voxvera/ --exclude=voxvera/vendor/
|
|
```
|
|
|
|
## 2. Update & Generate Localized Assets
|
|
|
|
Before releasing, you must ensure that **all documentation accurately reflects the new features and functions** introduced in the release.
|
|
|
|
All documentation and site templates must be synchronized with the translation system. This ensures that any changes to documentation are reflected across all 14+ supported languages.
|
|
|
|
### Synchronize Documentation
|
|
If you have modified any documentation templates in `docs/templates/` (which you should, to cover new features), you **must** use the translation system to regenerate the localized documentation before release:
|
|
```bash
|
|
# Regenerate docs/ folders for all languages from templates and locales
|
|
python3 -m voxvera.cli build-docs
|
|
```
|
|
|
|
### Synchronize Site Assets
|
|
The main `site/` directory (including QRs, HTML, and portable Zips) must also be refreshed to include the latest binary names and locale strings:
|
|
```bash
|
|
# Refresh site/ directory
|
|
python3 -m voxvera.cli build-site
|
|
```
|
|
|
|
## 3. Build Distribution Binaries
|
|
|
|
Linux CLI delivery is the supported deployment target today. Other package formats should be treated as experimental release artifacts until their Tor/OnionShare background-hosting behavior is validated end-to-end.
|
|
Capture platform evidence before promoting any support tier: run `bash scripts/platform-smoke.sh linux-cli` locally for the supported Linux path, and keep CI/workflow evidence aligned with the same command.
|
|
As other runtime targets mature, use `bash scripts/platform-smoke.sh macos-cli`, `bash scripts/platform-smoke.sh windows-cli`, or `bash scripts/platform-smoke.sh docker-cli` on their native environments before changing their support labels.
|
|
|
|
### Standard Binary
|
|
Generates an architecture-specific binary (e.g., `voxvera-linux-x86_64`) in `voxvera/resources/bin/`.
|
|
```bash
|
|
./scripts/build_binaries.sh
|
|
```
|
|
This directory is local build output only. Do not treat old files in `voxvera/resources/bin/` as canonical release history; the GitHub Release artifacts are the publish surface.
|
|
|
|
### AppImage (Linux)
|
|
Wraps the standard binary into a self-contained AppImage.
|
|
```bash
|
|
./packaging/build_appimage.sh
|
|
```
|
|
Experimental package surface.
|
|
|
|
### Flatpak (Linux)
|
|
Generates a standalone `.flatpak` bundle. Requires `flatpak-builder`.
|
|
```bash
|
|
./packaging/build_flatpak.sh
|
|
```
|
|
Experimental package surface.
|
|
|
|
### Debian Package (Linux)
|
|
Generates a `.deb` package for Debian/Ubuntu systems.
|
|
```bash
|
|
./packaging/build_deb.sh
|
|
```
|
|
Experimental package surface unless its runtime dependencies and recovery behavior are explicitly validated for the release.
|
|
|
|
### DMG (macOS)
|
|
Generates a `.dmg` installer for macOS (must be run on macOS).
|
|
```bash
|
|
./packaging/build_dmg.sh
|
|
```
|
|
Experimental package surface.
|
|
|
|
## 4. Release Execution
|
|
|
|
1. **Version Bump:** Update `__version__` in `voxvera/__init__.py` and `version` in `pyproject.toml`.
|
|
2. **Commit & Tag:**
|
|
```bash
|
|
git add .
|
|
git commit -m "chore: release vX.Y.Z"
|
|
git tag -a vX.Y.Z -m "VoxVera vX.Y.Z"
|
|
git push origin main --tags
|
|
```
|
|
## 5. Automated Releases (GitHub Actions)
|
|
|
|
The repository is configured with a **Build Standalone Binaries** workflow that automatically runs when a new tag (`v*`) is pushed. This workflow:
|
|
- Builds native executables for **Linux**, **Windows (.exe)**, and **macOS**.
|
|
- Automatically attaches these binaries to the corresponding GitHub Release.
|
|
|
|
This ensures that Windows users receive a professional `voxvera-windows.exe` rather than having to rely on `.bat` or `.sh` scripts.
|