pytest-selective 0.2.0__tar.gz → 0.4.0__tar.gz

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.github/test-lanes.json

@@ -18,14 +18,14 @@
       ],
       "inputs": [
         "src/**",
-        "scripts/**",
-        "tests/**",
-        ".pre-commit-config.yaml",
-        ".python-version"
+        "tests/**"
       ]
     }
   },
   "global_inputs": [
+    "scripts/**",
+    ".pre-commit-config.yaml",
+    ".python-version",
     "**/pyproject.toml",
     "pyproject.toml",
     "**/uv.lock",
@@ -33,9 +33,8 @@
     ".github/test-lanes.json",
     ".github/workflows/ci.yml",
     ".github/workflows/release.yml",
-    ".github/actions/**",
+    "actions/**",
     "action.yml",
-    "*/action.yml",
     "examples/**",
     ".github/workflows/public-actions.yml"
   ]

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.github/workflows/ci.yml

@@ -17,31 +17,40 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       lanes: ${{ steps.plan.outputs.lanes }}
+      mode: ${{ steps.files.outputs.mode }}
+      files: ${{ steps.files.outputs.test_roots_json }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - id: plan
-        uses: ./plan-lanes
+        uses: ./actions/plan-lanes
         with:
           config: .github/test-lanes.json
-          base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.run_attempt > 1 || github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'test:full') }}
+      - name: Share the repository graph and execution inputs with file selection
+        env:
+          PYTHONPATH: src
+        run: |
+          uv run --no-project --python 3.14 --with pydantic==2.13.4 --with pyyaml==6.0.3 \
+            python scripts/ci_file_config.py "$RUNNER_TEMP/test-impact.json"
+      - id: files
+        uses: ./
+        with:
+          config: ${{ runner.temp }}/test-impact.json
+          full-roots: tests
   quality:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
         with:
           python-version: '3.14'
       - run: uv run --locked pre-commit run --all-files
       - name: Check aggregate gate against the execution lanes
         run: >-
           uv run --no-project --python 3.14
-          --with "ci-esta>=0.1.0,<0.2.0"
+          --with "ci-esta>=1.1.0,<2.0.0"
           ci-esta check-workflow --workflow .github/workflows/ci.yml --lanes .github/test-lanes.json
-      - name: Validate routing even when the platform matrix is skipped
-        run: uv run --locked pytest -q tests/test_repository_ci.py
       - name: Validate GitHub Actions
         run: docker run --rm -v "$PWD:/repo" -w /repo rhysd/actionlint:1.7.7 -color
   tests:
@@ -57,20 +66,26 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
         with:
           python-version: ${{ matrix.python }}
       - name: Use native Git for Windows
-        uses: gigaverse-app/ci-esta/.github/actions/native-windows-git@v0.1
+        uses: gigaverse-app/ci-esta/actions/native-windows-git@v1
       - name: Record coverage runtime
         run: uv run --locked python -m coverage --version
-      - run: uv run --locked pytest -q -n 4 --durations=20 --junitxml=test-timings.xml --cov --cov-report=term-missing --cov-report=xml
+      - name: Execute the shared affected-file plan
+        run: uv run --locked python scripts/run_ci_tests.py -q -n 4 --durations=20 --junitxml=test-timings.xml
         env:
+          CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
+          CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}
+          CI_TEST_FILES: ${{ needs.select-tests.outputs.files }}
+          CI_COVERAGE: 'true'
           # Keep temporary Git repositories beside the checkout on the work disk.
           TMP: ${{ runner.temp }}
           TEMP: ${{ runner.temp }}
           TMPDIR: ${{ runner.temp }}
-      - uses: gigaverse-app/ci-esta/.github/actions/learn-test-timings@v0.1
+      - uses: gigaverse-app/ci-esta/actions/learn-test-timings@v1
+        if: ${{ hashFiles('test-timings.xml') != '' }}
         with:
           junit-pattern: test-timings.xml
           artifact-name: test-timings-${{ matrix.python }}-${{ matrix.os }}
@@ -89,22 +104,34 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
         with:
           python-version: '3.11'
       - run: uv pip install 'pytest==8.0.0'
-      - run: uv run --no-sync pytest -q -n 4 --durations=20
+      - name: Execute the same file plan on minimum pytest
+        run: uv run --no-sync python scripts/run_ci_tests.py -q -n 4 --durations=20
+        env:
+          CI_PLANNER_RESULT: ${{ needs.select-tests.result }}
+          CI_TEST_MODE: ${{ needs.select-tests.outputs.mode }}
+          CI_TEST_FILES: ${{ needs.select-tests.outputs.files }}
   distributions:
+    needs: select-tests
+    # README changes still need build/metadata checks; planner failure must not skip them.
+    if: ${{ !cancelled() }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
+      - uses: gigaverse-app/ci-esta/actions/setup-cached-uv@v1
         with:
           python-version: '3.14'
       - run: uv build
       - run: uv run --locked twine check --strict dist/*
       - run: uv run --locked python scripts/check_metadata.py
-      - run: uv run --locked python scripts/smoke_distribution.py
+      - name: Smoke installed distributions when runtime inputs change
+        if: >-
+          ${{ needs.select-tests.result != 'success' ||
+              fromJSON(needs.select-tests.outputs.lanes).tests }}
+        run: uv run --locked python scripts/smoke_distribution.py
       - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: distributions
@@ -117,7 +144,7 @@ jobs:
     if: ${{ !cancelled() }}
     runs-on: ubuntu-latest
     steps:
-      - uses: gigaverse-app/ci-esta/.github/actions/validation-gate@v0.1
+      - uses: gigaverse-app/ci-esta/actions/validation-gate@v1
         with:
           needs: ${{ toJSON(needs) }}
           lanes: ${{ needs.select-tests.outputs.lanes || '{}' }}

pytest_selective-0.4.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: documentation/requirements.txt
+      - run: python -m pip install -r documentation/requirements.txt
+      - run: python scripts/render_brand.py --check
+      - run: python -m mkdocs build --strict
+      - run: python documentation/check_site.py
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: documentation-site
+          path: site/
+          if-no-files-found: error

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.github/workflows/observe-ci.yml

@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   report:
-    uses: gigaverse-app/ci-esta/.github/workflows/report.yml@v0.3.0
+    uses: gigaverse-app/ci-esta/.github/workflows/report.yml@v1
     with:
       run-id: ${{ github.event.workflow_run.id }}
       run-attempt: ${{ github.event.workflow_run.run_attempt }}
@@ -22,3 +22,4 @@ jobs:
       post-sticky: true
       required-gates-json: '[{"kind":"actions_job","job_name":"Validation gate"}]'
       analyze-critical-path: true
+      test-selection-artifact: test-impact-explanation

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.github/workflows/public-actions.yml

@@ -7,7 +7,24 @@ on:
 permissions:
   contents: read
 jobs:
+  select-tests:
+    runs-on: ubuntu-latest
+    outputs:
+      lanes: ${{ steps.select.outputs.lanes }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: select
+        uses: ./actions/plan-lanes
+        with:
+          config: .github/test-lanes.json
+          artifact-name: public-action-selection
   public-actions:
+    needs: select-tests
+    if: >-
+      ${{ !cancelled() && (needs.select-tests.result != 'success' ||
+          fromJSON(needs.select-tests.outputs.lanes).tests) }}
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
@@ -37,7 +54,7 @@ jobs:
         run: |
           test "$MODE" = full
           test -n "$ROOTS"
-      - uses: ./plan-lanes
+      - uses: ./actions/plan-lanes
         id: lanes
         with:
           config: .github/test-lanes.json
@@ -52,3 +69,6 @@ jobs:
           import json, os
           assert json.loads(os.environ['LANES']) == {'tests': True}
           PY
+      - name: Require successful planning after fallback execution
+        if: ${{ !cancelled() && needs.select-tests.result != 'success' }}
+        run: exit 1

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.github/workflows/release.yml

@@ -54,7 +54,8 @@ jobs:
           if [[ ! "$RELEASE_TAG" =~ ^v([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
             exit 0
           fi
-          alias="v${BASH_REMATCH[1]}.${BASH_REMATCH[2]}"
+          # The Actions API has its own major, independent of the Python package.
+          alias="v1"
           if gh api "repos/$GH_REPO/git/ref/tags/$alias" --silent; then
             gh api --method PATCH "repos/$GH_REPO/git/refs/tags/$alias" \
               -f sha="$RELEASE_SHA" -F force=true --silent

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/.gitignore

@@ -11,3 +11,7 @@ dist/
 coverage.xml
 htmlcov/
 tutorial-report.json
+
+# Built documentation
+/site/
+/.venv-docs/

pytest_selective-0.4.0/.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+python:
+  install:
+    - requirements: documentation/requirements.txt
+mkdocs:
+  configuration: mkdocs.yml
+  fail_on_warning: true

pytest_selective-0.4.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.4.0"
+}

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/AGENTS.md

@@ -14,8 +14,8 @@ on pytest-selective itself.
 - Planning supports committed revisions and explicit working-tree snapshots. Preserve full execution on
   operational uncertainty and diagnostics for invalid declarations. An empty
   selection is not an empty pytest argument list.
-- Keep consumer routing regressions in the always-running quality job. Update
-  `.github/test-lanes.json` when adding execution inputs; preserve full main/manual
+- Select consumer routing regressions by their declared execution/configuration inputs. Update
+  `.github/test-lanes.json` when adding execution inputs; preserve explicit full/manual
   checkpoints and the `test:full` override.
 - The README's performance numbers are scenario-specific observations. Keep
   claims linked to [raw evidence](docs/benchmarks/2026-10-22-routing.md); distinguish
@@ -56,3 +56,14 @@ npx --yes @dallay/agentsync@1.52.3 status
 ```
 
 Keep the symlink tracked in Git. See CONTRIBUTING.md for platform setup.
+
+## Documentation-only CI
+
+Documentation-only PRs execute zero tests unless a test or lane explicitly
+declares that documentation as an input. This includes CI contract tests,
+installed-wheel smoke and public-action smoke. Metadata/link/build checks may
+still validate documentation without running runtime tests. Declare execution
+workflows, selector configuration, helpers, locks and non-import inputs; missing
+history or failed planning must execute the full affected lanes and fail the
+required planning gate. Ordinary PRs and pushes use selection; manual/release/scheduled/full overrides
+remain complete checkpoints.

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.4.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.3.0...v0.4.0) (2026-10-24)
+
+
+### Features
+
+* **actions:** simplify selection adoption with shared defaults ([#63](https://github.com/gigaverse-app/pytest-selective/issues/63)) ([85e082d](https://github.com/gigaverse-app/pytest-selective/commit/85e082dfdbcf2f8c02ac3de38613c818cb749807))
+
+## [0.3.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.2.0...v0.3.0) (2026-10-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* **actions:** named action callers upgrading from older layouts must replace `.github/actions/NAME` or `NAME` with `actions/NAME` and select a revision containing that path.
+
+### Features
+
+* **actions:** group public entry points under actions directory ([#44](https://github.com/gigaverse-app/pytest-selective/issues/44)) ([236aefc](https://github.com/gigaverse-app/pytest-selective/commit/236aefc83d9f0ee1696a5ffa29fc83cbcc4a53dc))
+
+
+### Bug fixes
+
+* **ci:** dogfood dependency-based test selection ([#57](https://github.com/gigaverse-app/pytest-selective/issues/57)) ([76afb69](https://github.com/gigaverse-app/pytest-selective/commit/76afb69cea84681bd661ec2bfff7be857b434129))
+* **ci:** select all runtime tests by declared dependencies ([9673e50](https://github.com/gigaverse-app/pytest-selective/commit/9673e50dd8a709db9347d2e325da242aca96cece))
+* **docs:** refresh cached artwork when branding changes ([5726530](https://github.com/gigaverse-app/pytest-selective/commit/5726530a445099e7cf24a1a7a89016fed0270308))
+
+
+### Refactoring
+
+* **actions:** move implementations into the public actions directory ([#46](https://github.com/gigaverse-app/pytest-selective/issues/46)) ([bd5aae3](https://github.com/gigaverse-app/pytest-selective/commit/bd5aae32176ae83b121d2353f40b562642184cd8))
+
 ## [0.2.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.1.1...v0.2.0) (2026-10-23)
 
 

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/CONTRIBUTING.md

@@ -54,14 +54,32 @@ limitations. The pull request template provides a short checklist. See
 ## CI lane selection
 
 This repository uses its own `plan-lanes` action. Documentation-only PRs keep
-quality checks (including Markdown links) and distribution build/install checks,
-while skipping the six-platform pytest matrix and minimum-pytest lane. Source,
-tests, scripts, dependency/pytest policy and workflow changes run the complete
-matrix. Main, manual/called runs and the `test:full` label run it in full; a
-failed planner also runs all tests. Repository routing controls exercise the
-committed config against real Git trees, including full and missing-history
+quality checks (including Markdown links) and distribution build/metadata checks,
+while skipping the six-platform pytest matrix and minimum-pytest lane. Within an
+admitted lane, the repository's public file-selection action selects affected
+test files once; the platform matrix and minimum-pytest job execute that same
+plan. CI-esta receives both lane and file explanations, learns JUnit timings,
+and validates the aggregate gate. Source and test edits follow dependencies;
+scripts, dependency/pytest policy and execution workflow changes retain full
+validation. Manual/called/release runs and the `test:full` label run it in full; a
+failed planner also runs all tests. Installed-distribution smoke checks use the
+same runtime-input decision; README-only changes skip those checks while still
+verifying the README embedded in both release archives. Repository routing
+controls exercise the committed config against real Git trees, including full and missing-history
 controls. Add new non-import execution inputs to `.github/test-lanes.json`.
 
+File planning derives its graph from that same lane config and merges its declared
+global execution inputs with the graph's environment inputs. Declare subprocess
+and non-import dependencies at their readers. Full plans collect whole-suite
+coverage; scoped plans produce JUnit timing evidence without presenting partial
+coverage as a whole-suite result. The small execution wrapper only consumes the
+public action's JSON file list: it does not implement another selector.
+The outer pytest process disables the selective plugin to avoid a second planner
+and a hidden dependency of every test on plugin startup. Plugin integration tests
+still load it normally in subprocesses and declare that dependency explicitly.
+Missing or failed planning runs complete roots, and an empty successful plan never starts
+pytest. The aggregate gate still fails when planning fails.
+
 ## Conventional Commits
 
 Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
@@ -123,3 +141,14 @@ the Linux filesystem. See the
 [Windows setup guide](https://dallay.github.io/agentsync/guides/windows-symlink-setup/).
 If AgentSync backs up an existing `CLAUDE.md`, review and preserve any unique
 guidance in `AGENTS.md`; do not commit the backup as another instruction source.
+
+## Documentation-only CI
+
+Documentation-only PRs execute zero tests unless a test or lane explicitly
+declares that documentation as an input. This includes CI contract tests,
+installed-wheel smoke and public-action smoke. Metadata/link/build checks may
+still validate documentation without running runtime tests. Declare execution
+workflows, selector configuration, helpers, locks and non-import inputs; missing
+history or failed planning must execute the full affected lanes and fail the
+required planning gate. Ordinary PRs and pushes use selection; manual/release/scheduled/full overrides
+remain complete checkpoints.

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 0.2.0
+Version: 0.4.0
 Summary: Explainable Python test impact analysis: select affected pytest files from Git changes
 Project-URL: Homepage, https://github.com/gigaverse-app/pytest-selective
-Project-URL: Documentation, https://github.com/gigaverse-app/pytest-selective/blob/main/docs/README.md
+Project-URL: Documentation, https://pytest-selective.readthedocs.io/en/latest/
 Project-URL: Repository, https://github.com/gigaverse-app/pytest-selective
 Project-URL: Issues, https://github.com/gigaverse-app/pytest-selective/issues
 Project-URL: Changelog, https://github.com/gigaverse-app/pytest-selective/blob/main/CHANGELOG.md
@@ -29,10 +29,9 @@ Provides-Extra: audit
 Requires-Dist: pytest>=8; extra == 'audit'
 Description-Content-Type: text/markdown
 
-# pytest-selective
-
-**Run affected Python tests. See why they matter.**
+![pytest-selective: Run affected Python tests. See why they matter.](https://raw.githubusercontent.com/gigaverse-app/pytest-selective/main/docs/assets/banner.png?v=17de2a0b7412)
 
+# pytest-selective
 [![CI](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/pytest-selective)](https://pypi.org/project/pytest-selective/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://github.com/gigaverse-app/pytest-selective/blob/main/pyproject.toml)
@@ -40,6 +39,11 @@ Description-Content-Type: text/markdown
 [![Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64?logo=ruff&logoColor=black)](https://github.com/gigaverse-app/pytest-selective/blob/main/.pre-commit-config.yaml)
 [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/gigaverse-app/pytest-selective/blob/main/LICENSE)
 [![Agent skill](https://img.shields.io/badge/Agent_Skill-ready-2563EB)](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/agents.md)
+[![Documentation](https://readthedocs.org/projects/pytest-selective/badge/?version=latest)](https://pytest-selective.readthedocs.io/en/latest/)
+
+**Run affected Python tests. See why they matter.**
+
+[Read the documentation](https://pytest-selective.readthedocs.io/en/latest/) · [Related tools](https://pytest-selective.readthedocs.io/en/latest/ecosystem/)
 
 pytest-selective is a **Python test impact analysis** tool for incremental testing
 with pytest. It follows dependencies through both sides of a Git change, selects
@@ -47,7 +51,8 @@ the affected test files, and explains the result. Use it directly as a pytest
 plugin, or plan before collection and service startup with the CLI and CI actions.
 
 Built from the selector used in Gigaverse's backend, AI, and shared Python
-infrastructure. The API may change before 1.0.
+infrastructure. Use the moving `@v1` Actions tag. The Python package has its own
+version and compatible dependency range.
 [Provenance and extraction scope](https://github.com/gigaverse-app/pytest-selective/blob/main/PROVENANCE.md).
 
 [Quick tutorial](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/tutorial.md) ·
@@ -66,12 +71,15 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
 | Avoid expensive collection and application imports | `pytest-selective run --config .github/test-impact.json -- -q` | Collection/imports for unaffected files as well as execution |
-| Plan affected files in GitHub Actions | `gigaverse-app/pytest-selective@main` | Plans before installing your application |
-| Keep whole-suite coverage or conformance checks | `gigaverse-app/pytest-selective/plan-lanes@main` | Entire unaffected jobs, including their services and setup |
+| Plan affected files in GitHub Actions | `gigaverse-app/pytest-selective@v1` | Plans before installing your application |
+| Keep whole-suite coverage or conformance checks | `gigaverse-app/pytest-selective/actions/plan-lanes@v1` | Entire unaffected jobs, including their services and setup |
 | Check assumptions about JSON, templates and other runtime inputs | Optional file-read recorder and dependency audit | Exposes observed reads missing from the declared graph |
 | Keep selection narrow as the project grows | Explanations, startup-floor budgets, expansion and isolation guards | Makes broad new fixture/import dependencies visible |
 
@@ -81,10 +89,9 @@ collects normally; the pre-collection runner and CI planner can avoid that cost.
 Keep full checkpoints and use complete lanes when partial suites cannot satisfy
 your coverage contract.
 
-**Public-path availability:** root and short action paths are new on `main`;
-existing `v0.1` releases predate them. Evaluate with `@main`, or pin a reviewed
-commit containing the public `action.yml`. Adopt a compatible release tag after
-it includes these paths. Existing `.github/actions/...` paths remain supported.
+**Public-path availability:** version 1 provides the root action and
+`actions/NAME` paths. Use the moving `@v1` tag for compatible updates.
+Older immutable releases retain their original layouts.
 [Public action API](docs/actions.md).
 
 ## Have your agent set it up
@@ -227,7 +234,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |
@@ -262,7 +269,7 @@ and evidence checks.
 inspectable JSON plans, runtime dependency audits, and planning before application
 startup. Both use static dependency analysis; choose
 based on your workflow, and validate selection against your own suite.
-See the [lessons from pytest-impacted](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/pytest-impacted.md)
+See the [comparison with pytest-impacted](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/comparison-pytest-impacted.md)
 for portability and Git-resolution improvements adopted from that comparison.
 
 ## Contribute

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/README.md

@@ -1,7 +1,6 @@
-# pytest-selective
-
-**Run affected Python tests. See why they matter.**
+![pytest-selective: Run affected Python tests. See why they matter.](https://raw.githubusercontent.com/gigaverse-app/pytest-selective/main/docs/assets/banner.png?v=17de2a0b7412)
 
+# pytest-selective
 [![CI](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/pytest-selective)](https://pypi.org/project/pytest-selective/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://github.com/gigaverse-app/pytest-selective/blob/main/pyproject.toml)
@@ -9,6 +8,11 @@
 [![Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64?logo=ruff&logoColor=black)](https://github.com/gigaverse-app/pytest-selective/blob/main/.pre-commit-config.yaml)
 [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/gigaverse-app/pytest-selective/blob/main/LICENSE)
 [![Agent skill](https://img.shields.io/badge/Agent_Skill-ready-2563EB)](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/agents.md)
+[![Documentation](https://readthedocs.org/projects/pytest-selective/badge/?version=latest)](https://pytest-selective.readthedocs.io/en/latest/)
+
+**Run affected Python tests. See why they matter.**
+
+[Read the documentation](https://pytest-selective.readthedocs.io/en/latest/) · [Related tools](https://pytest-selective.readthedocs.io/en/latest/ecosystem/)
 
 pytest-selective is a **Python test impact analysis** tool for incremental testing
 with pytest. It follows dependencies through both sides of a Git change, selects
@@ -16,7 +20,8 @@ the affected test files, and explains the result. Use it directly as a pytest
 plugin, or plan before collection and service startup with the CLI and CI actions.
 
 Built from the selector used in Gigaverse's backend, AI, and shared Python
-infrastructure. The API may change before 1.0.
+infrastructure. Use the moving `@v1` Actions tag. The Python package has its own
+version and compatible dependency range.
 [Provenance and extraction scope](https://github.com/gigaverse-app/pytest-selective/blob/main/PROVENANCE.md).
 
 [Quick tutorial](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/tutorial.md) ·
@@ -35,12 +40,15 @@ and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-
 
 ## Choose how to use it
 
+Follow the [adoption tutorial and checklist](docs/tutorials/adoption-checklist.md)
+for local execution, CI routing, dependency audits, timing feedback and measured rollout.
+
 | You want to… | Use | What it saves |
 | --- | --- | --- |
 | Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
 | Avoid expensive collection and application imports | `pytest-selective run --config .github/test-impact.json -- -q` | Collection/imports for unaffected files as well as execution |
-| Plan affected files in GitHub Actions | `gigaverse-app/pytest-selective@main` | Plans before installing your application |
-| Keep whole-suite coverage or conformance checks | `gigaverse-app/pytest-selective/plan-lanes@main` | Entire unaffected jobs, including their services and setup |
+| Plan affected files in GitHub Actions | `gigaverse-app/pytest-selective@v1` | Plans before installing your application |
+| Keep whole-suite coverage or conformance checks | `gigaverse-app/pytest-selective/actions/plan-lanes@v1` | Entire unaffected jobs, including their services and setup |
 | Check assumptions about JSON, templates and other runtime inputs | Optional file-read recorder and dependency audit | Exposes observed reads missing from the declared graph |
 | Keep selection narrow as the project grows | Explanations, startup-floor budgets, expansion and isolation guards | Makes broad new fixture/import dependencies visible |
 
@@ -50,10 +58,9 @@ collects normally; the pre-collection runner and CI planner can avoid that cost.
 Keep full checkpoints and use complete lanes when partial suites cannot satisfy
 your coverage contract.
 
-**Public-path availability:** root and short action paths are new on `main`;
-existing `v0.1` releases predate them. Evaluate with `@main`, or pin a reviewed
-commit containing the public `action.yml`. Adopt a compatible release tag after
-it includes these paths. Existing `.github/actions/...` paths remain supported.
+**Public-path availability:** version 1 provides the root action and
+`actions/NAME` paths. Use the moving `@v1` tag for compatible updates.
+Older immutable releases retain their original layouts.
 [Public action API](docs/actions.md).
 
 ## Have your agent set it up
@@ -196,7 +203,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | A transitive dependency | Import chains and package initialization |
 | A deleted or renamed module | Dependencies in both the base and head trees |
 | Fixtures or startup code | Ancestor conftests and configured global modules |
-| Templates, schemas, or data files | Reader-owned declarations and YAML sidecars |
+| Templates, schemas, or data files | [Reader-owned declarations and YAML sidecars](docs/tutorials/sidecar-dependencies.md) |
 | A surprisingly large selection | Dependency paths, startup-floor and blast-radius explanations |
 | A large CI suite | Cached parsing, graph reuse, and duration-based shard planning |
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |
@@ -231,7 +238,7 @@ and evidence checks.
 inspectable JSON plans, runtime dependency audits, and planning before application
 startup. Both use static dependency analysis; choose
 based on your workflow, and validate selection against your own suite.
-See the [lessons from pytest-impacted](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/pytest-impacted.md)
+See the [comparison with pytest-impacted](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/comparison-pytest-impacted.md)
 for portability and Git-resolution improvements adopted from that comparison.
 
 ## Contribute

{pytest_selective-0.2.0 → pytest_selective-0.4.0}/RELEASING.md

@@ -43,10 +43,17 @@ check out or build source with that permission.
    `pytest-selective --help` and run the tutorial using that installation.
 
 After a normal release publishes successfully, the workflow advances the
-compatible Actions tag (for example, `v0.1` for `v0.1.0`). Consumers can use
-`@v0.1` to receive patch releases. Package requirements use compatible ranges
-such as `pytest-selective>=0.1.0,<0.2.0`; lockfiles retain resolved versions and
-artifact hashes. Prereleases do not advance the Actions tag.
+Actions tag `v1`. The Actions API version is independent of the Python package
+version: publishing Python `0.x.y` does not prevent updating Actions `v1`.
+Consumers deliberately use `actions/NAME@v1` as a moving target. Change the
+Actions major only when deliberately establishing a new Actions API line.
+Package requirements use their own compatible ranges, such as
+`pytest-selective>=0.2,<0.3`; lockfiles retain resolved versions and artifact
+hashes. Prereleases do not advance the Actions tag.
+
+For an Actions-only publication, advance `v1` to the exact reviewed main commit
+after its complete CI passes. This updates the Git tag without creating a GitHub
+release or invoking PyPI publication. Do not move immutable package release tags.
 
 Manual dispatch is available for a version-matching **tag**, not a branch. The
 workflow intentionally does not skip existing uploads: investigate a partial