MAINT: switch to the src/ layout

.github/workflows/docs.yml

@@ -5,21 +5,19 @@ on:
     branches: [main]
     paths:
       - "docs/**"
-      - "schemas/**"
+      - "src/benchx/schemas/**"
       - "tools/gen_docs.py"
       - "zensical.toml"
       - "README.md"
-      - "benchx/README.md"
       - ".github/workflows/docs.yml"
   pull_request:
     branches: [main]
     paths:
       - "docs/**"
-      - "schemas/**"
+      - "src/benchx/schemas/**"
       - "tools/gen_docs.py"
       - "zensical.toml"
       - "README.md"
-      - "benchx/README.md"
       - ".github/workflows/docs.yml"
 
 concurrency:

.github/workflows/e2e.yml

@@ -93,20 +93,20 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/benchx/uv.lock
+          cache-dependency-glob: benchx/uv.lock
 
       # The scripts run plain `python`, `bx` and `spin`, and hard-code
       # lib/python3.12/site-packages, so this is Python 3.12 on the PATH. The `test`
       # extra is only for pyperf, which the benchmarks need.
       - name: Install benchx on Python 3.12
-        working-directory: benchx/benchx
+        working-directory: benchx
         run: |
           uv python install 3.12
           uv sync --extra test --python 3.12
           echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
 
       - name: Install NumPy's build tools
-        run: uv pip install --python benchx/benchx/.venv/bin/python spin ninja meson-python cython
+        run: uv pip install --python benchx/.venv/bin/python spin ninja meson-python cython
 
       # The full history and the tags: track.sh checks out v2.4.3 and v2.4.0.
       - name: Clone NumPy
@@ -121,7 +121,7 @@ jobs:
           mkdir -p "$RUNNER_TEMP/pin"
           cat > "$RUNNER_TEMP/pin/bx" <<EOF
           #!/bin/sh
-          exec taskset -c $BENCH_CPUS $PWD/benchx/benchx/.venv/bin/bx "\$@"
+          exec taskset -c $BENCH_CPUS $PWD/benchx/.venv/bin/bx "\$@"
           EOF
           chmod +x "$RUNNER_TEMP/pin/bx"
           echo "$RUNNER_TEMP/pin" >> "$GITHUB_PATH"
@@ -200,12 +200,12 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/benchx/uv.lock
+          cache-dependency-glob: benchx/uv.lock
 
       # The scripts run plain `python` and `bx`. benchx is installed in editable mode,
       # which is where it reads its schemas from.
       - name: Install benchx
-        working-directory: benchx/benchx
+        working-directory: benchx
         run: |
           uv python install 3.13
           uv sync --extra test --python 3.13
@@ -261,13 +261,13 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/benchx/uv.lock
+          cache-dependency-glob: benchx/uv.lock
 
       # The script runs plain `python` and `bx`, and the workers need pyperf, which the
       # `test` extra brings. benchx is installed in editable mode, which is where it reads
       # its schemas from.
       - name: Install benchx
-        working-directory: benchx/benchx
+        working-directory: benchx
         run: |
           uv python install 3.13
           uv sync --extra test --python 3.13
@@ -317,12 +317,12 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/benchx/uv.lock
+          cache-dependency-glob: benchx/uv.lock
 
       # The workers need pyperf, which the `test` extra brings. benchx is installed in
       # editable mode, which is where it reads its schemas from.
       - name: Install benchx
-        working-directory: benchx/benchx
+        working-directory: benchx
         run: |
           uv python install 3.13
           uv sync --extra test --python 3.13
@@ -332,8 +332,8 @@ jobs:
       # build is several GB of CUDA libraries that the runner has no use for.
       - name: Install NumPy and PyTorch
         run: |
-          uv pip install --python benchx/benchx/.venv/bin/python numpy
-          uv pip install --python benchx/benchx/.venv/bin/python torch --index-url https://download.pytorch.org/whl/cpu
+          uv pip install --python benchx/.venv/bin/python numpy
+          uv pip install --python benchx/.venv/bin/python torch --index-url https://download.pytorch.org/whl/cpu
 
       - name: Show what is under test
         run: |
@@ -381,14 +381,15 @@ jobs:
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/benchx/uv.lock
+          cache-dependency-glob: benchx/uv.lock
 
       # The script makes two venvs of its own with uv (Python 3.12, the newest with numpy
-      # 1.26.4 wheels) and installs benchx in both, from the checkout that the benchx of the
-      # active environment runs from. So this environment needs benchx in editable mode,
-      # which is also where it reads its schemas from. The venvs bring their own pyperf.
+      # 1.26.4 wheels) and installs benchx in both, from BENCHX_SRC (set on the run step).
+      # Left unset, it takes the checkout from the benchx of the active environment and assumes
+      # that the package sits directly in the project directory, which it does not under src/.
+      # The venvs bring their own pyperf.
       - name: Install benchx
-        working-directory: benchx/benchx
+        working-directory: benchx
         run: |
           uv python install 3.13
           uv sync --python 3.13
@@ -403,6 +404,8 @@ jobs:
 
       - name: Run the numpy-venvs example
         working-directory: benchx_examples/examples/numpy-venvs
+        env:
+          BENCHX_SRC: ${{ github.workspace }}/benchx
         run: bash ./run.sh
 
       - name: Upload the output

.github/workflows/tests.yml

@@ -4,14 +4,18 @@ on:
   push:
     branches: [main]
     paths:
-      - "benchx/**"
-      - "schemas/**"
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
       - ".github/workflows/**"
   pull_request:
     branches: [main]
     paths:
-      - "benchx/**"
-      - "schemas/**"
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
       - ".github/workflows/**"
 
 concurrency:
@@ -30,16 +34,13 @@ jobs:
       matrix:
         os: [ubuntu-latest, macos-latest]
         python-version: ["3.11", "3.13"]
-    defaults:
-      run:
-        working-directory: benchx
     steps:
       - uses: actions/checkout@v4
 
       - uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: benchx/uv.lock
+          cache-dependency-glob: uv.lock
 
       - name: Install Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
@@ -49,3 +50,28 @@ jobs:
 
       - name: Run tests
         run: uv run --extra test --python ${{ matrix.python-version }} python -m pytest tests -ra
+
+  # An editable install finds the schemas next to the source, so the matrix above cannot
+  # tell whether a wheel carries them. This installs the built wheel (not editable) into a
+  # clean environment, runs `bx` from outside the checkout, and runs the test suite that the
+  # wheel itself ships (benchx/tests), so it checks the wheel's contents as well as its code.
+  wheel:
+    name: wheel / py3.13
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build the wheel
+        run: uv build --wheel
+
+      - name: Install the wheel into a clean environment and test it
+        run: |
+          uv venv --python 3.13 "$RUNNER_TEMP/venv"
+          source "$RUNNER_TEMP/venv/bin/activate"
+          uv pip install "$(ls dist/*.whl)[test]"
+          # Away from the checkout, so that nothing can import it instead of the installed package.
+          cd "$RUNNER_TEMP"
+          bx --help
+          python -m pytest --pyargs benchx -ra

.gitignore

@@ -2,7 +2,12 @@
 .idea/
 site/
 .cache/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
 # generated by tools/gen_docs.py
 docs/index.md
-docs/benchx.md
 docs/schemas/

CHANGELOG.md

@@ -0,0 +1,15 @@
+# 0.1.0
+
+Initial release of `benchx`: most major features are implemented, and the project is
+ready for user testing. Please give it a spin on your benchmarking needs and let us
+know what is suboptimal or missing!
+
+The following users contributed to this release (listed alphabetically):
+
+Maanas Arora,
+Evgeni Burovski,
+Raúl Cumplido,
+Ralf Gommers,
+Marco Edward Gorelli,
+Rok Mihevc
+

README.md

@@ -25,22 +25,36 @@ lost.
 
 ## Grounded in user stories
 
-To make sure the schema and the components serve real needs, we are collecting
-user stories from multiple projects — who benchmarks,
-what they do today, where it hurts, what must not break. We surveyed Apache Arrow's
+To make sure the schema and the components serve real needs, started by collecting
+[user stories](https://benchx-dev.github.io/benchx/user_stories/) from multiple projects
+-- who benchmarks, what they do today, where it hurts, what must not break.
+We surveyed Apache Arrow's
 continuous benchmarking setup, NumPy, SciPy, Pandas, and several related projects from
 the data science/numerical computing ecosystem.
 The stories drive which components exist and what each must do; the schema must
 allow all of them.
 
+## BenchX usage and development
+
+We welcome contributions of all sorts: add a user story, tell us about your use case, try
+`benchx` on your workflow/project, open an issue if you found a rough edge,
+implement a missing feature.
+
+- Documentation: <https://benchx-dev.github.io/benchx/>
+- Issue tracker: <https://github.com/benchx-dev/benchx/issues/>
+- A collection of worked examples: <https://github.com/benchx-dev/benchx_examples>
+
+
 ## Contents
 
 - `docs/design/benchmark-result-schema.md` — the benchmark result schema and
   migration contract (the core design document).
 - `docs/user_stories/` — user story template and collected stories.
-- `schemas` -- JSON schemas for the benchmark result and other components.
-- `benchx/` -- an in-progress implementation.
-- `benchx/examples/` -- worked examples of benchmarking setup(s).
+- `src/benchx/` -- an in-progress implementation, with its tests in `tests/`.
+- `src/benchx/schemas/` -- JSON schemas for the benchmark result and other components
+  (shipped with the package).
+- worked examples of benchmarking setup(s) are in
+  [benchx_examples](https://github.com/benchx-dev/benchx_examples).
 
 ## Documentation site
 
@@ -53,14 +67,14 @@ uv run --with-requirements docs/requirements.txt python tools/gen_docs.py
 uv run --with-requirements docs/requirements.txt zensical serve
 ```
 
-`tools/gen_docs.py` generates the landing page, the benchx page, and the
+`tools/gen_docs.py` generates the landing page and the
 schema reference pages into `docs/` (those paths are gitignored); `zensical.toml`
 configures the site, and `.github/workflows/docs.yml` builds and deploys it.
 
 ## Status
 
-Beta. The main goal at this stage is to get the schema and the component
-boundaries right. The project is under active development, and we expect to be able to
+Beta status: the main features are available and ready for user testing;
+the project is under active development, and we expect to be able to
 start offering API stability guarantees in the near future.
 
 ## License