refactor(ci): restructure justfile and release workflows

.github/workflows/ci.yml

@@ -3,16 +3,16 @@ name: CI
 on:
   push:
     branches: [main]
-    tags-ignore: ['**']   # release.yml handles tags
   pull_request:
+  workflow_call:
 
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   lint:
-    name: Lint & type-check
+    name: Validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -55,13 +55,8 @@ jobs:
       - name: Install dependencies
         run: yarn install --immutable
 
-      - name: Install just
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just
-
       - name: Run unit tests
-        run: just unit-test
+        run: yarn test:unit
 
   build:
     name: Build
@@ -88,7 +83,7 @@ jobs:
         run: yarn install --immutable
 
       - name: Build & package
-        run: just build && just package
+        run: just package
 
       - name: Upload extension zip
         uses: actions/upload-artifact@v4

.github/workflows/release.yml

@@ -3,62 +3,53 @@ name: Release
 on:
   push:
     tags:
-      - "v*"
+      - 'v[0-9]*'
 
 permissions:
   contents: write
 
 jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
   release:
-    name: Build and Release
+    name: Create GitHub Release
     runs-on: ubuntu-latest
-
+    needs: [ci]
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install system dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y just gettext zip gnome-shell python3-gi gir1.2-glib-2.0
-
-      - name: Enable Corepack
-        run: corepack enable
+      - uses: actions/checkout@v4
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
+      - name: Download extension zip
+        uses: actions/download-artifact@v4
         with:
-          node-version: 22
-          cache: yarn
+          name: extension-zip
+          path: dist/target/
 
-      - name: Install dependencies
-        run: yarn install --immutable
-
-      - name: Build
-        run: just build
-
-      - name: Package
-        run: just package
+      - name: Detect pre-release
+        id: check
+        run: |
+          if [[ "${{ github.ref_name }}" == *"-rc"* ]]; then
+            echo "prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "prerelease=false" >> $GITHUB_OUTPUT
+          fi
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           name: ${{ github.ref_name }}
           files: dist/target/aurora-shell@luminusos.github.io.shell-extension.zip
           generate_release_notes: true
+          prerelease: ${{ steps.check.outputs.prerelease }}
 
-      - name: Create Release Branch
+      - name: Create maintenance branch
         run: |
-          # Extract the major version number from the tag string (e.g., v50.1 -> 50)
-          VERSION_NUM=${GITHUB_REF_NAME#v}
-          MAJOR_VERSION=$(echo "$VERSION_NUM" | cut -d. -f1)
-          BRANCH_NAME="release/v${MAJOR_VERSION}.x"
-
-          # Check if the branch already exists on the remote
-          if git ls-remote --exit-code --heads origin "$BRANCH_NAME"; then
-            echo "Branch $BRANCH_NAME already exists. Skipping creation."
+          MAJOR=$(echo "${{ github.ref_name }}" | sed 's/^v//' | grep -oP '^\d+')
+          BRANCH="release/v${MAJOR}.x"
+          if git ls-remote --exit-code --heads origin "$BRANCH" > /dev/null 2>&1; then
+            echo "Branch $BRANCH already exists, skipping."
           else
-            echo "Creating and pushing new branch $BRANCH_NAME based on the current tag's HEAD"
-            git checkout -b "$BRANCH_NAME"
-            git push origin "$BRANCH_NAME"
+            echo "Creating branch $BRANCH"
+            git checkout -b "$BRANCH"
+            git push origin "$BRANCH"
           fi

AGENTS.md

@@ -25,28 +25,34 @@ Do not leave a task incomplete if either command reports errors or failures.
 
 ## Commands
 
-- **Build:** `just build` — installs deps, compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
-- **Install:** `just install` — builds + packages as `.zip` + installs to GNOME Shell
-- **Quick update:** `just quick` — rebuild + rsync files to extension dir (skips full install)
+- **Install deps:** `just deps` — runs `yarn install`; use once or when updating packages
+- **Build:** `just build` — compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
+- **Package:** `just package` — packs the extension as a `.zip` in `dist/target/` (depends on `build`)
+- **Install:** `just install` — installs the already-packaged `.zip` to GNOME Shell (requires `just package` first)
+- **Full install:** `just full-install` — packages + installs in one step
+- **All:** `just all` — clean + full-install
 - **Uninstall:** `just uninstall` — disables and removes the extension
-- **Run (host):** `just run` — build + install + launch a devkit GNOME Shell session
+- **Run (host):** `just run` — launches a devkit GNOME Shell session (headless, Wayland)
 - **Run (toolbox):** `just toolbox run` — same as above, but inside the Fedora toolbox
-- **Create toolbox:** `just toolbox create` — create the `gnome-shell-devel` Fedora toolbox
+- **Create toolbox:** `just toolbox create` — create the `aurora-shell-devel` Fedora toolbox
 - **Remove toolbox:** `just toolbox remove` — delete the toolbox
-- **Type-check:** `just validate` — runs `tsc` without emitting output
-- **Lint:** `just lint` — runs ESLint
-- **Unit tests:** `just unit-test` — runs unit tests via `yarn test:unit` (vitest)
-- **Single integration test:** `just test <script>` — runs one shell test script with `gnome-shell-test-tool` (headless); requires `just package` first
-- **All integration tests:** `just test-all` — builds and runs all `tests/shell/aurora*.js` scripts on the host, printing a pass/fail summary
-- **All integration tests (toolbox):** `just toolbox test-all` — same as above but runs inside the Fedora toolbox (preferred; use this instead of `just test-all`)
+- **Validate:** `just validate` — runs tsc, ESLint, Prettier check, and Stylelint
+- **Lint:** `just lint` — runs ESLint only
 - **Watch SCSS:** `just watch` — watches `src/styles/` and recompiles on change
 - **View logs:** `just logs` — shows recent `aurora` entries from the current boot journal
 - **Clean:** `just clean` — removes `dist/`
 - **Deep clean:** `just distclean` — removes `dist/` and `node_modules/`
+- **Unit tests:** `just unit-test` — runs unit tests via `yarn test:unit` (vitest)
+- **Coverage:** `just coverage` — runs unit tests with coverage report
+- **Single integration test:** `just test <script>` — packages and runs one shell test script headlessly (e.g., `just test tests/shell/auroraTrayIcons.js`)
+- **All integration tests:** `just test-all` — packages and runs all `tests/shell/aurora*.js` on the host, printing a pass/fail summary
+- **All integration tests (toolbox):** `just toolbox test-all` — same as above but inside the Fedora toolbox (preferred; use this instead of `just test-all`)
+- **Single integration test (toolbox):** `just toolbox test <script>` — packages and runs one test inside the toolbox
+- **Vagrant VM:** `just vagrant create|run|ssh|remove` — Vagrant-based devkit VM (mirrors `toolbox` but uses a full Fedora VM via Vagrant)
 
 ### Translation commands
 
-- **Regenerate POT template:** `just pot` — scans compiled JS (`dist/`) and rewrites `po/aurora-shell@luminusos.github.io.pot` with all `_()` strings. Run this whenever translatable strings are added or removed.
+- **Regenerate POT template:** `just pot` — builds then scans compiled JS (`dist/`) and rewrites the `.pot` file with all `_()` strings. Run this whenever translatable strings are added or removed.
 - **Merge new strings into .po files:** `just update-po` — runs `msgmerge` on every `po/*.po` file against the current `.pot`. Run after `just pot`.
 - **Compile .mo binaries:** `just compile-mo` — compiles each `po/*.po` into `dist/locale/<lang>/LC_MESSAGES/*.mo`. Called automatically by `just build`.
 
@@ -76,7 +82,7 @@ Do not leave a task incomplete if either command reports errors or failures.
   - `unit/` — vitest unit tests (metadata, registry, schema)
   - `shell/` — GNOME Shell integration test scripts (run via `gnome-shell-test-tool`)
 - `.github/workflows/ci.yml` — CI pipeline (lint + type-check → unit tests + build → integration tests)
-- `scripts/` — helper shell scripts (`create-toolbox.sh`, `run-gnome-shell.sh`, `bump-version.sh`)
+- `scripts/` — helper shell scripts (`create-toolbox.sh`, `run-gnome-shell.sh`, `run-vagrant-gnome-shell.sh`)
 - `esbuild.ts` — esbuild bundler configuration
 - `sass.config.ts` — Sass compiler configuration
 - `justfile` — all project commands

CONTRIBUTING.md

@@ -117,32 +117,89 @@ just unit-test
 
 After these steps, your module appears in Preferences and respects the runtime enable/disable toggles.
 
+## Branching & Release Model
+
+Aurora Shell follows a branching model aligned with GNOME Shell's own release cycle.
+
+### Branches
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Active development targeting the next GNOME release |
+| `release/v50.x` | Maintenance branch for GNOME 50 |
+| `release/v51.x` | Maintenance branch for GNOME 51 |
+
+Maintenance branches are created automatically when the first tag for a new major version is pushed.
+
+### New features
+
+New features land on `main` and are released alongside a new major GNOME Shell version. **Do not add new features to maintenance branches** — they are strictly for bug fixes.
+
+### Bug fixes
+
+Bug fixes should target `main` first via a normal PR. If the fix is relevant to a maintenance release, open a **separate PR targeting that branch**:
+
+```bash
+git checkout release/v50.x
+git cherry-pick <commit-sha>
+# open a PR targeting release/v50.x
+```
+
+Maintainers decide which fixes are worth backporting. Not every fix needs to land in every maintenance branch.
+
+### Release candidates
+
+Release candidates are published alongside GNOME Shell RCs. Tags follow the pattern `v50-rc1`, `v50-rc2`, etc. RC releases are automatically marked as **pre-releases** on GitHub.
+
+### Stable releases
+
+Stable releases use tags like `v50.1`, `v50.2`, matching the GNOME Shell major version they target.
+
+To publish a release, create an annotated tag and push it:
+
+```bash
+git tag -a v50.1 -m "Release v50.1"
+git push origin v50.1
+```
+
+The CI pipeline runs all tests and, if they pass, publishes the GitHub Release automatically.
+
 ## Build System & Commands
 
-- **Build:** `just build` — installs deps, compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
-- **Install:** `just install` — builds + packages as `.zip` + installs to GNOME Shell
-- **Quick update:** `just quick` — rebuild + rsync files to extension dir (skips full install)
-- **Run (host):** `just run` — build + install + launch a devkit GNOME Shell session
-- **Type-check:** `just validate` — runs `tsc` without emitting output
-- **Lint:** `just lint` — runs ESLint
+- **Install deps:** `just deps` — runs `yarn install`; use once or when updating packages
+- **Build:** `just build` — compiles TypeScript and SCSS, copies metadata/schemas, compiles `.mo` files
+- **Package:** `just package` — packs the extension as a `.zip` in `dist/target/` (depends on `build`)
+- **Install:** `just install` — installs the already-packaged `.zip` to GNOME Shell (requires `just package` first)
+- **Full install:** `just full-install` — packages + installs in one step
+- **All:** `just all` — clean + full-install
+- **Uninstall:** `just uninstall` — disables and removes the extension
+- **Run (host):** `just run` — launches a devkit GNOME Shell session (headless, Wayland)
+- **Validate:** `just validate` — runs tsc, ESLint, Prettier check, and Stylelint
+- **Lint:** `just lint` — runs ESLint only
 - **Unit tests:** `just unit-test` — runs unit tests via vitest (no GNOME Shell required)
-- **Single integration test:** `just test <script>` — runs one shell test headlessly with `gnome-shell-test-tool`
-- **All integration tests:** `just test-all` — builds and runs all shell tests, printing a pass/fail summary
+- **Coverage:** `just coverage` — runs unit tests with coverage report
+- **Single integration test:** `just test <script>` — packages and runs one shell test headlessly
+- **All integration tests:** `just test-all` — packages and runs all shell tests on the host, printing a pass/fail summary
 - **Watch SCSS:** `just watch` — watches `src/styles/` and recompiles on change
+- **View logs:** `just logs` — shows recent `aurora` entries from the current boot journal
+- **Clean:** `just clean` — removes `dist/`
+- **Deep clean:** `just distclean` — removes `dist/` and `node_modules/`
 
-*Note: For a full test environment, you can create a Fedora toolbox via `just toolbox create` and run session testing inside it using `just toolbox run`.*
+*For a full test environment, create a Fedora toolbox via `just toolbox create` and run tests inside it using `just toolbox test-all` (preferred over `just test-all`).*
 
 ## CI
 
-Every push and pull request runs the CI pipeline defined in `.github/workflows/ci.yml`. It has four jobs:
+Every push to `main` and every pull request runs the CI pipeline defined in `.github/workflows/ci.yml`. It has four jobs:
 
-1. **Lint & type-check** — runs `yarn validate` and `yarn lint`
+1. **Validate** — runs tsc, ESLint, Prettier check, and Stylelint via `just validate`
 2. **Unit & regression tests** — runs `yarn test:unit` (vitest, no GNOME Shell needed)
 3. **Build** — runs `just package` and uploads the extension `.zip` as an artifact (depends on lint)
 4. **Integration tests** — runs all `tests/shell/aurora*.js` scripts against a headless GNOME Shell inside a Fedora container (depends on build + unit tests)
 
 All jobs must pass before a PR can be merged.
 
+When a version tag (`v50.1`, `v50-rc1`, etc.) is pushed, `.github/workflows/release.yml` calls the CI pipeline and, if all jobs pass, publishes the GitHub Release automatically.
+
 ## Coding Standards
 
 - **File names:** `camelCase.ts`

justfile

@@ -10,7 +10,7 @@ default:
 deps:
     yarn install
 
-build: deps
+build:
     yarn build
     cp metadata.json dist/
     cp -r data/schemas dist/ 2>/dev/null || true
@@ -48,11 +48,13 @@ lint:
 watch:
     yarn watch:css
 
-install: package
+install:
     gnome-extensions install --force dist/target/{{ uuid }}.shell-extension.zip
     glib-compile-schemas {{ ext_dir }}/schemas/
     @echo "Installed at: {{ ext_dir }}"
 
+full-install: package install
+
 uninstall:
     gnome-extensions uninstall {{ uuid }}
     @echo "Uninstalled."
@@ -109,7 +111,7 @@ compile-mo:
         echo "Compiled $po -> $outdir/$DOMAIN.mo"
     done
 
-all: clean build install
+all: clean full-install
     @echo "Complete installation finished."
 
 unit-test: