Skip to content

docs: update README download links and RELEASING.md for v2.1.0 release #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SynTechRev merged 1 commit into from
Apr 12, 2026
Merged

docs: update README download links and RELEASING.md for v2.1.0 release #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,28 @@ Legistar-based jurisdiction or custom legal corpus.

**Desktop App (no installation prerequisites):**

Pre-built installers will be available in the [Releases](https://github.com/SynTechRev/ODIA/releases) section soon. For now, build the desktop application locally:
Download the standalone desktop application — no Python, Docker, or command line
required. All analysis runs locally on your machine.

```bash
# Build desktop application
cd desktop
npm install
npm run build:backend # Build Python backend
cd ../frontend
npm ci
ELECTRON_BUILD=1 npm run build # Build frontend for Electron
cd ../desktop
npm run build # Create installer for your platform
```
Download the latest version from the [**Releases page**](https://github.com/SynTechRev/ODIA/releases/latest):
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link to /releases/latest will still 404 until at least one non-draft release is published. If this README is intended to work before the first release is created, consider linking to /releases (list page) or explicitly marking this link as only valid after the first release is published.

Suggested change
Download the latest version from the [**Releases page**](https://github.com/SynTechRev/ODIA/releases/latest):
Download the latest version from the [**Releases page**](https://github.com/SynTechRev/ODIA/releases):

Copilot uses AI. Check for mistakes.

| Platform | Installer | Architecture |
|----------|-----------|--------------|
| **Windows** | `ODIA-Setup-2.1.0.exe` | x64 |
| **macOS** | `ODIA-2.1.0.dmg` | x64, arm64 (Universal) |
| **Linux** | `ODIA-2.1.0.AppImage` | x64 |

**Direct download links (after v2.1.0 release):**
- [Windows x64](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-Setup-2.1.0.exe)
- [macOS Universal](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-2.1.0.dmg)
Comment on lines +28 to +33
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The macOS row/linking assumes a single “Universal” DMG (ODIA-2.1.0.dmg), but the current electron-builder config builds separate x64 and arm64 artifacts (not a combined universal DMG). This will make the architecture info and direct download link inaccurate for Apple Silicon. Either update the docs to list both DMGs (and their filenames/links), or update the build config to produce a true universal artifact.

Suggested change
| **macOS** | `ODIA-2.1.0.dmg` | x64, arm64 (Universal) |
| **Linux** | `ODIA-2.1.0.AppImage` | x64 |
**Direct download links (after v2.1.0 release):**
- [Windows x64](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-Setup-2.1.0.exe)
- [macOS Universal](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-2.1.0.dmg)
| **macOS** | Separate DMGs on the Releases page | x64 (Intel), arm64 (Apple Silicon) |
| **Linux** | `ODIA-2.1.0.AppImage` | x64 |
**Direct download links (after v2.1.0 release):**
- [Windows x64](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-Setup-2.1.0.exe)
- [macOS (choose Intel x64 or Apple Silicon arm64 asset)](https://github.com/SynTechRev/ODIA/releases/tag/v2.1.0)

Copilot uses AI. Check for mistakes.
- [Linux AppImage](https://github.com/SynTechRev/ODIA/releases/download/v2.1.0/ODIA-2.1.0.AppImage)

**System Requirements:**
- **Windows:** Windows 10 (64-bit) or later
- **macOS:** macOS 10.15 (Catalina) or later
- **Linux:** Ubuntu 18.04+ or equivalent (requires libfuse2)

Installers are output to `desktop/dist/`. See [desktop/README.md](desktop/README.md) for detailed build instructions and platform-specific requirements.
See [desktop/README.md](desktop/README.md) for installation instructions and troubleshooting.

**With Docker (no Python/Node required):**
```bash
Expand Down
306 changes: 260 additions & 46 deletions docs/RELEASING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,78 +1,292 @@
# Release Process
# ODIA Release Process

## Automated Desktop Releases
## Overview

Desktop application releases are automated via GitHub Actions
(`.github/workflows/release-desktop.yml`).
ODIA uses automated GitHub Actions workflows to build and publish desktop application releases. This document describes the release process and troubleshooting steps.

### Creating a New Release
## Automated Release Process

1. **Update version** in relevant package files:
### Prerequisites

```bash
# Update desktop/package.json version field to X.Y.Z
# Update pyproject.toml version field to X.Y.Z
```
- [ ] All tests passing on `master` branch
- [ ] Desktop app builds successfully locally (optional verification)
- [ ] Version numbers updated in:
- `pyproject.toml` (line 7)
- `desktop/package.json` (line 3)
Comment on lines +14 to +15
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The prerequisites list hard-codes line numbers for pyproject.toml and desktop/package.json. These will drift over time and can mislead readers; consider removing the line references or linking to the files/keys instead.

Suggested change
- `pyproject.toml` (line 7)
- `desktop/package.json` (line 3)
- `pyproject.toml`
- `desktop/package.json`

Copilot uses AI. Check for mistakes.
- [ ] CHANGELOG.md updated (if exists) or release notes prepared
- [ ] README.md download links point to correct version

2. **Commit version bump:**
### Creating a Release

1. **Ensure you're on the latest master:**
```bash
git add desktop/package.json pyproject.toml
git commit -m "chore: bump version to X.Y.Z"
git push
git checkout master
git pull origin master
```

3. **Create and push tag:**

2. **Create and push the version tag:**
```bash
git tag vX.Y.Z
git push origin vX.Y.Z
git tag v2.1.0
git push origin v2.1.0
```

4. **GitHub Actions automatically:**
- Builds desktop installers for Windows, macOS, and Linux
- Creates a GitHub Release
- Uploads installers as release assets
- Generates release notes
3. **Monitor the build:**
- Go to: https://github.com/SynTechRev/ODIA/actions
- Watch the "Build and Release Desktop Apps" workflow
- Expected duration: 15-20 minutes
- Three jobs run in parallel (Windows, macOS, Linux)

5. **Verify release:**
- Check <https://github.com/SynTechRev/ODIA/releases>
4. **Verify the release:**
- Check: https://github.com/SynTechRev/ODIA/releases
- Verify three installers are attached:
- `ODIA-Setup-X.Y.Z.exe` (Windows)
- `ODIA-X.Y.Z.dmg` (macOS)
- `ODIA-X.Y.Z.AppImage` (Linux)
- Test download links work
- Download and test installers on each platform
- Download and test installers (recommended)

### What the Workflow Does

The `.github/workflows/release-desktop.yml` workflow:

1. **Builds Python backend** using PyInstaller
2. **Builds frontend** as static export for Electron
3. **Creates native installers** using electron-builder:
- **Windows:** NSIS installer (`.exe`)
- **macOS:** DMG disk image (`.dmg`) - Universal binary (x64 + arm64)
- **Linux:** AppImage (`.AppImage`)
Comment on lines +41 to +57
Copy link

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section states macOS produces a “Universal binary (x64 + arm64)” and implies only one .dmg, but desktop/package.json is configured to build two separate DMGs (x64 and arm64). The release verification checklist should reflect the actual set of assets (e.g., both DMGs) or the build config should be changed to generate a universal DMG.

Copilot uses AI. Check for mistakes.
4. **Creates GitHub Release** with auto-generated release notes
5. **Uploads installers** as release assets

### Version Numbering

Follow Semantic Versioning (semver): `MAJOR.MINOR.PATCH`

### Manual Release (Fallback)
- **MAJOR:** Breaking changes, incompatible API changes
- **MINOR:** New features, backwards-compatible
- **PATCH:** Bug fixes, backwards-compatible

If the automated release fails:
Examples:
- `v2.1.0` → `v2.1.1` (bug fix)
- `v2.1.0` → `v2.2.0` (new feature)
- `v2.1.0` → `v3.0.0` (breaking change)

---

## Manual Release (Fallback)

If the automated workflow fails, you can build and release manually.

### Local Build Requirements

**All Platforms:**
- Node.js 20+
- Python 3.11+
- Git

**Platform-Specific:**
- **Windows:** Windows 10+ (for Windows builds)
- **macOS:** macOS 10.15+ with Xcode Command Line Tools (for macOS builds)
- **Linux:** Ubuntu 18.04+ with build-essential, fakeroot, rpm, libfuse2

### Manual Build Steps

```bash
# Build locally for your platform
# 1. Install Python dependencies
pip install -e ".[dev]"
pip install pyinstaller

# 2. Build Python backend
cd desktop
npm ci
npm run build:backend

# 3. Build frontend for Electron
cd ../frontend
npm ci
ELECTRON_BUILD=1 npm run build

# 4. Copy frontend to desktop build directory
cd ..
mkdir -p desktop/build/frontend
cp -r frontend/out/. desktop/build/frontend/

# 5. Build installer for your platform
cd desktop
npm run build:win # Windows
npm run build:mac # macOS
npm run build:linux # Linux

# Manually create a release on GitHub and upload installers from desktop/dist/
# Installers output to: desktop/dist/
```

### Manual Release Creation

1. Go to: https://github.com/SynTechRev/ODIA/releases/new
2. **Tag:** `v2.1.0` (create new tag)
3. **Title:** `ODIA v2.1.0 - Desktop Release`
4. **Description:** Add release notes (see template below)
5. **Attach files:** Upload installers from `desktop/dist/`
6. **Publish release**

---

## Release Notes Template

```markdown
## ODIA v2.1.0

### 🎉 First Official Release

This is the first official release of ODIA (Oraculus DI Auditor) featuring desktop applications for Windows, macOS, and Linux.

### 📱 New Features

- **Desktop Application:** Standalone Electron app for offline document analysis
- Native file dialogs
- Automatic Python backend management
- Cross-platform support (Windows, macOS, Linux)

- **Mobile Application:** React Native/Expo mobile app (source available)
- 9 TypeScript-ported analysis detectors
- Offline-first architecture
- 118 tests at 97% coverage

### 🔍 Analysis Capabilities

- Fiscal anomaly detection
- Constitutional issues analysis
- Surveillance concerns identification
- Procurement timeline analysis
- Cross-jurisdiction boundary detection

### 📥 Downloads

| Platform | File | Size |
|----------|------|------|
| Windows (x64) | ODIA-Setup-2.1.0.exe | ~XXX MB |
| macOS (Universal) | ODIA-2.1.0.dmg | ~XXX MB |
| Linux (x64) | ODIA-2.1.0.AppImage | ~XXX MB |

### 📚 Documentation

- [Desktop App README](https://github.com/SynTechRev/ODIA/blob/master/desktop/README.md)
- [Quick Start Guide](https://github.com/SynTechRev/ODIA/blob/master/QUICKSTART.md)
- [Architecture Overview](https://github.com/SynTechRev/ODIA/blob/master/docs/ARCHITECTURE.md)

### 🐛 Known Issues

None reported yet. Please report issues at https://github.com/SynTechRev/ODIA/issues

### 🙏 Acknowledgments

Built with contributions from the Copilot coding agent and the open-source community.

---

**Full Changelog**: https://github.com/SynTechRev/ODIA/commits/v2.1.0
```

---

## Troubleshooting

### Build Fails on GitHub Actions

**Check the logs:**
1. Go to https://github.com/SynTechRev/ODIA/actions
2. Click on the failed workflow run
3. Expand the failed job
4. Review error messages

**Common issues:**

| Error | Cause | Fix |
|-------|-------|-----|
| `frontend/out not found` | Frontend build failed | Check ELECTRON_BUILD env var is set |
| `PyInstaller failed` | Python dependencies missing | Verify requirements.txt complete |
| `electron-builder failed` | Missing native dependencies | Check platform-specific dependencies |
| `Permission denied` | File permissions issue | Check file modes in repo |

### Release Not Created

**Verify:**
- Tag was pushed: `git ls-remote --tags origin`
- Tag format is correct: `v*.*.*` (e.g., `v2.1.0`, not `2.1.0`)
- Workflow has `contents: write` permission (already configured)
- Workflow completed successfully without errors

### Download Links Return 404

**Possible causes:**
1. Release not published yet (still draft)
2. Asset file names don't match links
3. Using `/latest/` before any release exists

**Fix:**
- Use specific version in URLs: `/download/v2.1.0/filename`
- Verify exact filenames in release assets
- Ensure release is published (not draft)

### Installer Doesn't Run

**Windows:**
- "Windows protected your PC" → Click "More info" → "Run anyway"
- SmartScreen warning expected for unsigned executables

**macOS:**
- "Cannot be opened because it is from an unidentified developer"
- Right-click → Open → Confirm
- Or: System Preferences → Security & Privacy → "Open Anyway"

**Linux:**
- Make executable: `chmod +x ODIA-*.AppImage`
- Install FUSE: `sudo apt install libfuse2`

---

## Release Checklist

- [ ] Version bumped in `desktop/package.json`
- [ ] Version bumped in `pyproject.toml`
- [ ] CHANGELOG updated (if maintained)
- [ ] All tests passing (`pytest` and `cd desktop && npm test`)
- [ ] Desktop app builds successfully locally
- [ ] Tag created and pushed (`git tag vX.Y.Z && git push origin vX.Y.Z`)
- [ ] GitHub Actions workflow completes without errors
- [ ] Release appears on <https://github.com/SynTechRev/ODIA/releases>
- [ ] Download links tested
- [ ] Installers tested on target platforms (Windows, macOS, Linux)
Use this checklist for each release:

### Pre-Release
- [ ] All tests passing on master
- [ ] Version updated in `pyproject.toml`
- [ ] Version updated in `desktop/package.json`
- [ ] README.md download links updated
- [ ] Release notes prepared

### Release
- [ ] Tag created and pushed
- [ ] GitHub Actions workflow triggered
- [ ] All three builds completed successfully
- [ ] Release created automatically
- [ ] Installers attached to release

### Post-Release
- [ ] Download links tested (no 404s)
- [ ] Windows installer tested
- [ ] macOS installer tested
- [ ] Linux AppImage tested
- [ ] GitHub Release marked as "Latest release"

---

## Future Automation Ideas

## Workflow Overview
- **Automated version bumping** via conventional commits
- **Changelog generation** from commit messages
- **Pre-release builds** for testing
- **Code signing** for Windows/macOS installers
- **Auto-update mechanism** in desktop app
- **Homebrew formula** for macOS installation
- **Snap/Flatpak packages** for Linux

The release workflow (`.github/workflows/release-desktop.yml`) runs on:
---

- **Version tags** matching `v*.*.*` (e.g., `v2.1.0`) — full build + release
- **Manual dispatch** — full build + artifact upload (no release created unless on a tag)
## Resources

The existing CI workflow (`.github/workflows/desktop-build.yml`) handles
continuous integration builds for pull requests and branch pushes.
- [Electron Builder Docs](https://www.electron.build/)
- [GitHub Actions - Creating Releases](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
- [Semantic Versioning](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
Loading