chore: migrate project management to pixi

.gitattributes

@@ -0,0 +1 @@
+pixi.lock linguist-generated=true

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-# Basic workflow for building and testing the pip installation
+# Test locked Pixi environments and the lowest supported PyPI dependencies.
 
 name: Continuous Integration
 
@@ -11,46 +11,49 @@ on:
 
 jobs:
   test:
-    name: py${{ matrix.versions.python-version }} ${{ matrix.versions.resolution }} ${{ matrix.deps.name}}
+    name: ${{ matrix.environment }} ${{ matrix.extras }}
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        versions:
-          - python-version: '3.10'
-            resolution: lowest-direct
-          - python-version: '3.11'
-            resolution: highest
-          - python-version: '3.12'
-            resolution: highest
-        deps:
-          - name: minimal
-            value: '[dev]'
-            doctest: '' # doctest runs MCA and requires statsmodels
-          - name: complete
-            value: '[dev,complete]'
+        include:
+          - environment: lowest
+            extras: '[dev]'
+          - environment: lowest
+            extras: '[dev,complete]'
+            doctest: '--doctest-glob=README.md'
+          - environment: minimal-py311
+          - environment: default # Python 3.11 with complete dependencies
+            doctest: '--doctest-glob=README.md'
+          - environment: minimal-py312
+          - environment: complete-py312
             doctest: '--doctest-glob=README.md'
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup Python ${{ matrix.versions.python-version }}
-        uses: actions/setup-python@v5
+      - name: Set up Pixi
+        uses: prefix-dev/setup-pixi@v0.11.2
         with:
-          python-version: ${{ matrix.versions.python-version }}
+          pixi-version: v0.82.1
+          environments: ${{ matrix.environment }}
+          locked: true
+          # Do not cache packages installed outside the lockfile by uv.
+          cache: ${{ matrix.environment != 'lowest' }}
 
-      - name: Install dependencies
-        run: |
-          pip install uv
-          uv pip install .${{ matrix.deps.value }} -r pyproject.toml \
-             --system --resolution ${{ matrix.versions.resolution }}
+      - name: Install lowest supported dependencies
+        if: matrix.environment == 'lowest'
+        run: pixi run --locked -e lowest install-lowest ".${{ matrix.extras }}"
+
+      - name: Build wheel and source distribution
+        if: matrix.environment == 'default'
+        run: pixi run --locked build
 
       - name: Execute Tests
         run: |
-          coverage run -m pytest -n auto ${{ matrix.deps.doctest }}
-          coverage report -m
-          coverage xml
+          pixi run --locked -e ${{ matrix.environment }} coverage ${{ matrix.doctest }}
+          pixi run --locked -e ${{ matrix.environment }} coverage-report
 
       - name: Upload Coverage Report to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v5
         with:
           files: ./coverage.xml

.github/workflows/formatting.yml

@@ -12,17 +12,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Install Python
-        uses: actions/setup-python@v5
+      - name: Set up Pixi
+        uses: prefix-dev/setup-pixi@v0.11.2
         with:
-          python-version: "3.11"
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          # Keep in sync with pyproject.toml and .pre-commit-config.yaml.
-          pip install ruff==0.3.4
+          pixi-version: v0.82.1
+          environments: lint
+          locked: true
       # Update output format to enable automatic inline annotations.
       - name: Run Ruff
         run: |
-          ruff check
-          ruff format --check
+          pixi run --locked -e lint lint
+          pixi run --locked -e lint format-check

.gitignore

@@ -110,6 +110,7 @@ celerybeat.pid
 *.sage.py
 
 # Environments
+.pixi/
 .env
 .venv
 env/

.readthedocs.yml

@@ -1,30 +1,16 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
 version: 2
 
-# Use mamba instead of conda
 build:
-  os: "ubuntu-20.04"
+  os: "ubuntu-24.04"
   tools:
-    python: "mambaforge-4.10"
-
-
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-   configuration: docs/conf.py
-
-# Optionally build your docs in additional formats such as PDF
-#formats:
-#   - pdf
-
-# Optionally set the version of Python and requirements required to build your docs
-conda:
-  environment: docs/environment.yml
-
-# python:
-#    version: 3.7
-#    install:
-#    - requirements: requirements.txt
+    python: "3.11"
+  jobs:
+    create_environment:
+      - asdf plugin add pixi
+      - asdf install pixi 0.82.1
+      - asdf global pixi 0.82.1
+    install:
+      - pixi install --locked -e docs
+    build:
+      html:
+        - pixi run --locked -e docs sphinx-build -T -b html docs "$READTHEDOCS_OUTPUT/html"

README.md

@@ -124,7 +124,20 @@ For a more comprehensive overview and usage examples, visit the [documentation](
 
 ## Contributing
 
-Contributions are highly welcomed and appreciated. If you're interested in improving `xeofs` or fixing issues, please read our [Contributing Guide](https://xeofs.readthedocs.io/en/latest/overview_3_contributing.html).
+Contributions are highly welcomed and appreciated. If you're interested in improving `xeofs` or fixing issues, please read our [Contributing Guide](https://xeofs.readthedocs.io/en/latest/content/contributing.html).
+
+For local development, [install Pixi](https://pixi.sh/latest/installation/) and
+run these commands from your clone:
+
+```sh
+pixi install --locked
+pixi run test
+pixi run -e lint lint
+pixi run -e docs docs
+```
+
+Pixi installs an editable copy of `xeofs` and uses the committed `pixi.lock`.
+Installing released packages with pip or Conda is unchanged.
 
 ## License
 

docs/content/contributing.rst

@@ -42,21 +42,61 @@ This command sequence creates a local directory named *xeofs* and links your ver
 2. Set up your development environment
 --------------------------------------
 
-Using the commands below, prepare your environment:
+Install `Pixi <https://pixi.sh/latest/installation/>`__, then prepare your
+environment from the repository root:
 
 .. code-block:: bash
 
-    conda create -n xeofs python=3.11 rpy2 pandoc
-    conda activate xeofs
-    pip install -e .[complete,docs,dev]
+    pixi install --locked
 
-This will install both core and optional dependencies, including those for specialized models, documentation, and development. Alternatively, you can skip some of the optional dependency sets (``[complete,docs,dev]``) depending on which components of the package you're working on.
+The default environment installs Python 3.11, an editable copy of ``xeofs``,
+development tools, and the ``complete`` optional dependencies. Pixi manages
+the environment in ``.pixi/``; no separate Conda environment or activation is
+needed. Use ``pixi run`` to execute commands, or ``pixi shell`` for an
+interactive shell.
+
+The dependency declarations remain in ``pyproject.toml`` and the resolved
+versions for Linux, macOS, and Windows are recorded in ``pixi.lock``. After
+changing dependencies, run ``pixi lock`` and commit both files. To update
+resolved packages without changing the requirements, run ``pixi update``.
+
+Other environments are available for specific tasks:
+
+.. code-block:: bash
+
+    pixi run -e minimal-py311 test
+    pixi run -e minimal-py312 test
+    pixi run -e complete-py312 test
+    pixi run -e lint lint
+    pixi run -e lint format-check
+    pixi run -e docs docs
+    pixi run build
+
+The documentation environment includes R, rpy2, and Pandoc and is available
+on Linux and macOS. The other locked environments also support Windows.
+
+CI additionally tests Python 3.10 with the lowest supported PyPI dependencies.
+Because Pixi does not expose PyPI's ``lowest-direct`` resolution strategy,
+this check uses ``uv`` inside a separate Pixi-managed environment:
+
+.. code-block:: bash
+
+    pixi run -e lowest install-lowest '.[dev]'
+    pixi run -e lowest coverage
+    pixi run -e lowest install-lowest '.[dev,complete]'
+    pixi run -e lowest coverage --doctest-glob=README.md
+
+These compatibility-check dependencies are intentionally resolved afresh,
+not locked. To switch back from complete to minimal dependencies, remove
+only ``.pixi/envs/lowest`` first so optional packages do not leak into the
+minimal check.
 
 Additionally, install the pre-commit hooks:
 
 .. code-block:: bash
 
-    pre-commit install
+    pixi run pre-commit install
+    pixi run pre-commit install --hook-type commit-msg
 
 If you've completed Steps 1 and 2, you can move directly to Step 4.
 
@@ -90,7 +130,7 @@ After making your updates, remember to commit them:
 .. code-block:: bash
 
     git add .
-    git commit -m "concise commit message"
+    git commit -m "fix: concise description of the bug fix"
 
 
 .. note::
@@ -99,6 +139,15 @@ After making your updates, remember to commit them:
 
     - Use **fix:** prefix for **bug fixes**. This will trigger a patch release.
     - Use **feat:** prefix for **new features**. This will initiate a minor release.
+    - Add **!** for **breaking changes**, for example ``feat!: change the public API``.
+      This will trigger a major release.
+    - Use **chore:** for maintenance that should not trigger a release.
+
+    Releases run automatically after merging onto ``main``. Use the same
+    conventional commit format for the pull request title when squash-merging.
+    Python Semantic Release continues to update ``project.version`` in
+    ``pyproject.toml`` and build the wheel and source distribution with
+    setuptools. Publishing does not depend on Pixi or its development lockfile.
 
 
 
@@ -109,7 +158,8 @@ It's essential to test any modifications to ensure compatibility with the existi
 
 .. code-block:: bash
 
-    pytest
+    pixi run test
+    pixi run test-readme
 
 If you introduce a new feature or function, please also add corresponding tests in the `tests` directory.
 
@@ -126,6 +176,5 @@ Once satisfied with your changes, push them to your GitHub fork:
 Then, on your GitHub fork page, select "Compare & pull request" to initiate the pull request.
 
 
-.. _convential commit: https://www.conventionalcommits.org/en/v1.0.0/
+.. _conventional commit: https://www.conventionalcommits.org/en/v1.0.0/
 .. _xarray Contributing Guide: https://docs.xarray.dev/en/stable/contributing.html#version-control-git-and-github
-