feat: Add CI and Release workflows for automated testing and publishing; update documentation in AGENTS.md, CHANGELOG.md, DEVELOP.md, and INSTALL.md

2026-08-28 11:33:25 +00:00 · 2026-04-12 11:52:42 +03:00
parent 7605a7d2fc
commit 1b50d15eea
6 changed files with 182 additions and 18 deletions
@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y libmediainfo-dev
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Type check
+        run: uv run mypy src/ --ignore-missing-imports
@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    name: Build and publish release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install system dependencies
+        run: sudo apt-get install -y libmediainfo-dev
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build distribution
+        run: uv build
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Create short-name and latest aliases
+        run: |
+          cp dist/moma-${{ steps.version.outputs.version }}-py3-none-any.whl dist/moma-${{ steps.version.outputs.version }}.whl
+          cp dist/moma-${{ steps.version.outputs.version }}-py3-none-any.whl dist/moma-latest.whl
+          cp dist/moma-${{ steps.version.outputs.version }}.tar.gz dist/moma-latest.tar.gz
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: "moma v${{ steps.version.outputs.version }}"
+          tag_name: ${{ github.ref_name }}
+          body: |
+            ## moma v${{ steps.version.outputs.version }}
+
+            See [CHANGELOG.md](https://github.com/shadoll/moma/blob/main/CHANGELOG.md) for details.
+
+            ### Install
+
+            ```bash
+            # With uv — always latest
+            uv tool install https://github.com/shadoll/moma/releases/latest/download/moma-latest.whl
+
+            # With uv — specific version
+            uv tool install https://github.com/shadoll/moma/releases/download/${{ github.ref_name }}/moma-${{ steps.version.outputs.version }}.whl
+
+            # With pip
+            pip install https://github.com/shadoll/moma/releases/download/${{ github.ref_name }}/moma-${{ steps.version.outputs.version }}.whl
+            ```
+          files: |
+            dist/moma-${{ steps.version.outputs.version }}.whl
+            dist/moma-${{ steps.version.outputs.version }}.tar.gz
+            dist/moma-latest.whl
+            dist/moma-latest.tar.gz
+          draft: false
+          prerelease: false
@@ -776,25 +776,41 @@ uv run bump-version
 uv run release  # Bump + sync + build
 ```

+### CI / GitHub Actions
+
+Two workflows in `.github/workflows/`:
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | Push to `main`, PRs | Tests + mypy on Python 3.11 and 3.12 |
+| `release.yml` | Push of `v*.*.*` tag | Tests → build → publish to GitHub Releases |
+
+**To publish a release**: commit bumped version → `git tag vX.Y.Z` → `git push --tags`.  
+CI runs tests, builds wheel + tarball, creates a GitHub Release with packages attached.
+
 ### Release Checklist

 - [ ] All tests passing: `uv run pytest`
 - [ ] Type checking passes: `uv run mypy src/`
- [ ] Documentation updated (CHANGELOG.md, README.md)
- [ ] Version bumped in `pyproject.toml`
+- [ ] Documentation updated (CHANGELOG.md, README.md, AGENTS.md)
+- [ ] Version bumped in `pyproject.toml`: `uv run bump-version`
 - [ ] Dependencies synced: `uv sync`
- [ ] Build successful: `uv build`
- [ ] Install test: `uv tool install .`
+- [ ] Tag pushed: `git tag vX.Y.Z && git push --tags`
+- [ ] CI release workflow passes (GitHub Actions)
 - [ ] Manual testing with real media files

 ### Build Artifacts

+Built locally with `uv build` or automatically by CI on tag push:
+
 ```
 dist/
 ├── moma-0.8.11-py3-none-any.whl    # Wheel distribution
 └── moma-0.8.11.tar.gz              # Source distribution
 ```

+Released packages are attached to each [GitHub Release](https://github.com/shadoll/moma/releases).
+
 ---

 ## API Integration
@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+### Added
+- **GitHub Actions CI** (`ci.yml`): runs tests + mypy on Python 3.11 and 3.12 for every push to `main` and all PRs
+- **GitHub Actions Release** (`release.yml`): triggered by `v*.*.*` tags — runs tests, builds wheel + tarball, publishes packages as GitHub Release assets
+
 ### Future Plans
 See [docs/REFACTORING_PROGRESS.md](docs/REFACTORING_PROGRESS.md) and [docs/ToDo.md](docs/ToDo.md) for upcoming features and improvements.

@@ -87,19 +87,34 @@ See [AGENTS.md - Testing Strategy](AGENTS.md#testing-strategy)
 ## Release Process

 ```bash
-# 1. Bump version
+# 1. Bump version (increments patch in pyproject.toml)
 uv run bump-version

-# 2. Run full release
+# 2. Run full release (bump + sync + build)
 uv run release

-# 3. Test installation
+# 3. Test installation locally
 uv tool install .

 # 4. Manual testing
 uv run moma /path/to/test/media
+
+# 5. Tag and push — CI builds and publishes to GitHub Releases automatically
+git tag v$(grep '^version' pyproject.toml | grep -o '[0-9.]*')
+git push origin main --tags
 ```

+### CI / GitHub Actions
+
+Two workflows live in `.github/workflows/`:
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | Push to `main`, PRs | Run tests + mypy on Python 3.11 and 3.12 |
+| `release.yml` | Push of `v*.*.*` tag | Run tests, build wheel + tarball, publish as GitHub Release |
+
+**To publish a release**: bump version → commit → `git tag vX.Y.Z` → `git push --tags`. CI handles the rest.
+
 See [AGENTS.md - Release Process](AGENTS.md#release-process)

 ---
@@ -24,13 +24,16 @@ powershell -c "irm https://astral.sh/uv/install.sh | iex"

 #### Install moma
 ```bash
-# One-command install from remote wheel
-uv tool install https://github.com/shadoll/moma/raw/branch/main/dist/moma-0.8.11-py3-none-any.whl
+# Always-latest stable URL (recommended)
+uv tool install https://github.com/shadoll/moma/releases/latest/download/moma-latest.whl

-# Or from local wheel (if downloaded)
-uv tool install dist/moma-0.8.11-py3-none-any.whl
+# Specific version
+uv tool install https://github.com/shadoll/moma/releases/download/v0.8.11/moma-0.8.11.whl

-# Or from PyPI (when published)
+# From a locally downloaded wheel
+uv tool install moma-latest.whl
+
+# From PyPI (when published)
 uv tool install moma
 ```

@@ -42,14 +45,12 @@ moma /path/to/directory # Scan specific directory

 ### Method 2: pip Install from Wheel

-If you have the wheel file, you can install it with pip.
-
 ```bash
-# Install the wheel
-pip install dist/moma-0.8.11-py3-none-any.whl
+# Always-latest stable URL
+pip install https://github.com/shadoll/moma/releases/latest/download/moma-latest.whl

-# Or install globally (may require sudo)
-sudo pip install dist/moma-0.8.11-py3-none-any.whl
+# From a locally downloaded wheel
+pip install moma-latest.whl
 ```

 ### Method 3: Development Installation
@@ -115,6 +116,12 @@ python3 src/main.py /path/to/directory
 - Python 3.11+ (official installer)
 - MediaInfo (automatically handled by pymediainfo)

+## Downloading Releases
+
+All release packages (`.whl` and `.tar.gz`) are attached to each [GitHub Release](https://github.com/shadoll/moma/releases). Releases are built automatically by CI when a version tag (`v*.*.*`) is pushed.
+
+---
+
 ## Verification

 After installation, verify it works: