docs: add UPDATE guide and bump version references to v0.4.0-alpha (#83)

2026-01-28 20:10:12 -08:00
parent 924c5a2861
commit 5e4f781254
3 changed files with 191 additions and 7 deletions
@@ -7,10 +7,10 @@ This guide provides detailed instructions for installing Vocalinux on Linux syst
 ### One-liner Installation (Recommended)

 ```bash
-curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.3.0-alpha
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.4.0-alpha
 ```

-> **Note**: Installs the latest stable release (v0.3.0-alpha). For the most recent version, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases).
+> **Note**: Installs v0.4.0-alpha. For other versions, check [GitHub Releases](https://github.com/jatinkrmalik/vocalinux/releases).

 That's it! The installer handles everything automatically, including Whisper AI support.

@@ -341,8 +341,18 @@ rm -f ~/.local/share/icons/hicolor/scalable/apps/vocalinux*.svg
 gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
 ```

+## Updating Vocalinux
+
+Already have Vocalinux installed? See the [Update Guide](UPDATE.md) for instructions on upgrading to the latest version.
+
+Quick update command:
+```bash
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.4.0-alpha
+```
+
 ## Getting Help

 - 📖 [User Guide](USER_GUIDE.md)
+- 📖 [Update Guide](UPDATE.md)
 - 🐛 [Report Issues](https://github.com/jatinkrmalik/vocalinux/issues)
 - 💬 [Discussions](https://github.com/jatinkrmalik/vocalinux/discussions)
@@ -0,0 +1,172 @@
+# Updating Vocalinux
+
+This guide explains how to update Vocalinux to the latest version.
+
+## Quick Update (Recommended)
+
+### If You Installed via curl (One-liner)
+
+Simply re-run the installation command with the new version tag:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.4.0-alpha
+```
+
+The installer will:
+- Update your existing installation
+- Preserve your configuration and models
+- Install any new dependencies
+
+> **Note**: The installer automatically detects and updates existing installations.
+
+### If You Installed from Source
+
+```bash
+cd vocalinux
+git fetch origin
+git checkout v0.4.0-alpha
+./install.sh
+```
+
+Or to always get the latest main branch:
+
+```bash
+cd vocalinux
+git pull origin main
+./install.sh
+```
+
+---
+
+## Detailed Update Methods
+
+### Method 1: Reinstall via Installer (Easiest)
+
+The installer handles everything automatically:
+
+```bash
+# From the repo (if you have it cloned)
+cd vocalinux
+./install.sh --tag=v0.4.0-alpha
+
+# Or via curl (for any installation)
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.4.0-alpha
+```
+
+**What gets preserved:**
+- Your configuration at `~/.config/vocalinux/`
+- Your speech models at `~/.local/share/vocalinux/models/`
+- Your custom settings and preferences
+
+### Method 2: Manual Update (Advanced)
+
+If you prefer manual control over the update process:
+
+```bash
+# 1. Navigate to your vocalinux directory
+cd vocalinux
+
+# 2. Pull the latest changes
+git fetch origin
+git checkout v0.4.0-alpha
+
+# 3. Activate your virtual environment
+source venv/bin/activate
+
+# 4. Update the package
+pip install --upgrade .
+
+# 5. Exit and restart
+exit
+vocalinux
+```
+
+---
+
+## Checking Your Current Version
+
+To see which version you have installed:
+
+```bash
+# Check the package version
+python3 -c "import vocalinux; print(vocalinux.version.__version__)"
+
+# Or check from the repo
+git describe --tags
+```
+
+---
+
+## What's New in v0.4.0-alpha
+
+- **Multi-language support**: French, German, and Russian
+- **Debian 13+ compatibility**: Fixed appindicator package issues
+- **Python 3.12+ support**: Improved venv handling
+- **Better install script**: Tag-based version selection
+
+See the [full changelog](https://github.com/jatinkrmalik/vocalinux/releases/tag/v0.4.0-alpha).
+
+---
+
+## Troubleshooting
+
+### Update Won't Install
+
+**Symptom:** Installation fails during update
+
+**Solution:** Run the uninstaller first, then reinstall:
+
+```bash
+# Keep your config and models
+./uninstall.sh --keep-config --keep-data
+
+# Reinstall
+curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh | bash -s -- --tag=v0.4.0-alpha
+```
+
+### Old Version Still Running
+
+**Symptom:** After update, old version is still active
+
+**Solution:** Fully exit and restart:
+
+```bash
+# Kill any running instances
+pkill -f vocalinux
+
+# Start fresh
+vocalinux
+```
+
+### Dependencies Changed
+
+**Symptom:** New version has different system dependencies
+
+**Solution:** The installer handles this, but if you see errors:
+
+```bash
+sudo apt update
+sudo apt install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0
+```
+
+---
+
+## Automatic Updates (Coming Soon)
+
+We're working on an in-app update mechanism. For now, please use the manual update methods above.
+
+To check if a new version is available:
+
+```bash
+# Check latest release
+curl -s https://api.github.com/repos/jatinkrmalik/vocalinux/releases/latest | grep "tag_name"
+```
+
+---
+
+## Need Help?
+
+- 📖 [Installation Guide](INSTALL.md)
+- 📖 [User Guide](USER_GUIDE.md)
+- 🐛 [Report Issues](https://github.com/jatinkrmalik/vocalinux/issues)
+- 💬 [Discussions](https://github.com/jatinkrmalik/vocalinux/discussions)