Merge pull request #46 from saezlab/dev

chore: merge dev into main for v1.0.0-beta.4 release

Author: pablormier

.github/RELEASE_TEMPLATE.md

@@ -18,14 +18,14 @@ The automated release notes will be generated first, then you can add additional
 ## 📦 Installation
 
 ```bash
-pip install corneto==VERSION_PLACEHOLDER
+pip install corneto==<version-without-v-prefix>
 ```
 
 ## 📖 Documentation
 
-- [📚 Documentation](https://saezlab.github.io/corneto/)
+- [📚 Documentation](https://saezlab.github.io/corneto/stable/)
 - [🚀 Getting Started](https://saezlab.github.io/corneto/stable/install.html)
-- [📑 API Reference](https://saezlab.github.io/corneto/stable/api)
+- [📑 API Reference](https://saezlab.github.io/corneto/stable/api/)
 
 <!-- The automated release notes will be appended below this line -->
 ---

.github/workflows/build-and-publish.yml

@@ -59,6 +59,15 @@ jobs:
               echo "Valid release tag detected: ${version}"
               echo "should_publish=true" >> $GITHUB_OUTPUT
               echo "version=${version}" >> $GITHUB_OUTPUT
+              echo "pypi_version=${version#v}" >> $GITHUB_OUTPUT
+              # Mark alpha/beta/rc tags as GitHub pre-releases automatically.
+              if [[ "${version}" =~ -(alpha|beta|rc)([.-].*)?$ ]]; then
+                echo "is_prerelease=true" >> $GITHUB_OUTPUT
+                echo "make_latest=false" >> $GITHUB_OUTPUT
+              else
+                echo "is_prerelease=false" >> $GITHUB_OUTPUT
+                echo "make_latest=true" >> $GITHUB_OUTPUT
+              fi
               ;;
             *)
               echo "Not a v* tag: ${GITHUB_REF}, skipping publishing"
@@ -80,21 +89,22 @@ jobs:
           tag_name: ${{ steps.validate_tag.outputs.version }}
           name: Release ${{ steps.validate_tag.outputs.version }}
           generate_release_notes: true
-          make_latest: true
+          prerelease: ${{ steps.validate_tag.outputs.is_prerelease }}
+          make_latest: ${{ steps.validate_tag.outputs.make_latest }}
           files: |
             dist/*
           body: |
             ## 📦 Installation
 
             ```bash
-            pip install corneto==${{ steps.validate_tag.outputs.version }}
+            pip install corneto==${{ steps.validate_tag.outputs.pypi_version }}
             ```
 
             ## 📖 Documentation
 
-            - [📚 Documentation](https://saezlab.github.io/corneto/)
-            - [🚀 Getting Started](https://saezlab.github.io/corneto/install.html)
-            - [📑 API Reference](https://saezlab.github.io/corneto/api/)
+            - [📚 Documentation](https://saezlab.github.io/corneto/stable/)
+            - [🚀 Getting Started](https://saezlab.github.io/corneto/stable/install.html)
+            - [📑 API Reference](https://saezlab.github.io/corneto/stable/api/)
 
             ---
 

.github/workflows/deploy-docs.yml

@@ -68,7 +68,7 @@ jobs:
         run: |
           pip install poetry
           poetry self add "poetry-dynamic-versioning[plugin]"
-          poetry install --with dev,docs
+          poetry install --with dev --extras docs
 
       - name: Debug Git state and version
         run: |

.github/workflows/unit-tests.yml

@@ -34,6 +34,9 @@ jobs:
         pip install poetry
         poetry self add "poetry-dynamic-versioning[plugin]"
         poetry install
+    - name: Validate pinned wasm-graphviz checksum
+      run: |
+        poetry run python scripts/check_wasm_graphviz_checksum.py
     - name: Test with pytest
       run: |
         poetry run pytest

CONTRIBUTING.md

@@ -6,7 +6,7 @@ We value community input and look forward to opening up for contributions once w
 
 ## Setup environment
 
-We use [Poetry](https://python-poetry.org) for dependency management and [Nox](https://nox.thea.codes/) for task automation. Please follow the instructions to install `poetry` on your system: https://python-poetry.org/docs/#installing-with-pipx. We recommend to install poetry using `pipx`.
+We use [Poetry](https://python-poetry.org) for dependency management and task execution. Please follow the instructions to install `poetry` on your system: https://python-poetry.org/docs/#installing-with-pipx. We recommend to install poetry using `pipx`.
 
 For notebook execution in tutorials, we also support [Pixi](https://pixi.sh/) environments for isolated execution per tutorial directory.
 
@@ -139,13 +139,6 @@ We use `pytest` for running our automated tests. You can run tests in several wa
 poetry run pytest
 ```
 
-### Using Nox (recommended):
-```bash
-nox -s tests
-```
-
-The nox approach is recommended as it creates an isolated environment and ensures consistent testing across different setups. Nox is our primary task runner that provides standardized environments for testing, linting, formatting, and documentation building.
-
 This command will run all test files in your project that follow the `test_*.py` naming convention, as recognized by `pytest`.
 
 ### Writing Tests
@@ -162,47 +155,22 @@ def test_calculate_division():
         calculate_division(5, 0)
 ```
 
-## Code Quality and Testing with Nox
-
-We use [Nox](https://nox.thea.codes/) to standardize testing, linting, and documentation building across different environments. Nox provides isolated virtual environments for running different tasks and supports multiple Python versions.
-
-### Available Nox Sessions
-
-- **Testing**: Run unit tests across supported Python versions (3.10, 3.11, 3.12)
-  ```bash
-  nox -s tests  # Uses your current Python version
-  # Or specify a version if you have multiple:
-  nox -s "tests-3.10"  # Python 3.10
-  nox -s "tests-3.11"  # Python 3.11
-  nox -s "tests-3.12"  # Python 3.12
-  ```
-
-- **Linting**: Check code style and quality with ruff
-  ```bash
-  nox -s lint
-  ```
-
-- **Formatting**: Auto-fix code formatting issues
-  ```bash
-  nox -s format
-  ```
-
-- **Type Checking**: Run static type analysis with pyrefly
-  ```bash
-  nox -s typing
-  ```
-
-- **Documentation**: Build HTML documentation
-  ```bash
-  nox -s docs
-  ```
+## Code Quality and Testing
 
+### Linting
+```bash
+poetry run ruff check corneto --exclude tests
+```
 
-### Running All Quality Checks
+### Formatting
+```bash
+poetry run ruff check corneto --exclude tests --fix
+poetry run ruff format corneto --exclude tests
+```
 
-To run all quality checks (linting, formatting, typing, and tests) at once:
+### Type Checking
 ```bash
-nox -s lint format typing tests
+poetry run pyrefly check corneto
 ```
 
 ## Generating the documentation
@@ -211,51 +179,52 @@ This project uses Sphinx along with the PyData Sphinx theme to generate HTML doc
 
 ### Documentation for the current version
 
-To generate the HTML documentation for the current version of the project using nox:
+To generate the HTML documentation for the current version of the project using pixi:
 
 ```bash
-nox -s docs
+pixi run docs
 ```
 
 This command will build the documentation in the `docs/_build/html` directory, which you can open in a browser to view.
 
 ### Additional Documentation Options
 
-We provide several nox sessions for different documentation needs:
+We provide several pixi tasks for different documentation needs:
 
 - **Clean build**: Remove previous builds and rebuild documentation
   ```bash
-  nox -s docs_clean
+  pixi run docs-force
   ```
 
 - **Force notebook execution**: Build docs with forced notebook execution
   ```bash
-  nox -s docs_force
+  pixi run docs-force
   ```
 
 - **Strict mode**: Build docs treating warnings as errors
   ```bash
-  nox -s docs_werror
+  pixi run python -m sphinx-build -b html -W docs docs/_build/html
   ```
 
 - **Complete build**: Clean, force notebook execution, and build with warnings as errors
   ```bash
-  nox -s docs_all
+  pixi run docs-force
+  pixi run python -m sphinx-build -b html -W docs docs/_build/html
   ```
 
 - **Link checking**: Verify all external links in documentation
   ```bash
-  nox -s docs_linkcheck
+  pixi run python -m sphinx-build -b linkcheck docs docs/_build/linkcheck
   ```
 
 - **Serve locally**: Build and serve documentation at http://localhost:8000
   ```bash
-  nox -s docs_serve
+  pixi run docs-serve
   ```
 
 - **Full local check**: Build HTML documentation
   ```bash
-  nox -s docs_full
+  pixi run docs
   ```
 
 ### Notebook Execution with Pixi
@@ -269,7 +238,7 @@ poetry run python docs/tutorials/run_notebooks.py
 
 ### Additional notes
 
-- **Task automation**: All documentation, testing, and quality assurance tasks are standardized through nox sessions defined in `noxfile.py`.
+- **Task automation**: Testing and code quality are run via poetry commands; documentation tasks use pixi tasks defined in `pixi.toml`.
 - **`myst-nb`**: We use `myst-nb` to handle the conversion of Jupyter notebooks (`.ipynb` files) into HTML. If your contribution involves notebooks, make sure they render correctly in the generated documentation.
 - **Pixi integration**: Tutorial notebooks can use individual `pixi.toml` files for isolated execution environments with specific dependencies.
 - **Poetry and PEP 621**: The project uses both Poetry (legacy) and modern PEP 621 project configuration in `pyproject.toml`.

RELEASE.md

@@ -8,25 +8,30 @@ CORNETO uses an automated tag-based release process powered by Poetry Dynamic Ve
 
 To create a new release:
 
-1. **Create and push a Git tag** following semantic versioning:
+1. **Merge `dev` into `main`** via pull request.
+
+2. **Create and push the release tag from `main`**:
    ```bash
-   git tag -a v1.2.3 -m "v1.2.3"
-   git push origin v1.2.3
+   poetry install
+   git checkout main
+   git pull --ff-only origin main
+   poetry run release v1.2.3
    ```
+   - Use pre-release tags as needed: `v1.2.3-alpha.0`, `v1.2.3-beta.0`, `v1.2.3-rc.0`.
 
-2. **Automatic pipeline execution**:
+3. **Automatic pipeline execution**:
    - GitHub Actions detects the new tag
    - Builds the package using Poetry
    - **Creates GitHub Release with automated release notes**
    - Publishes to PyPI via OIDC trusted publishing
    - Deploys versioned documentation to GitHub Pages
 
-3. **Version resolution**:
+4. **Version resolution**:
    - Poetry Dynamic Versioning automatically extracts the version from the Git tag
    - The package version in `pyproject.toml` remains at `0.0.0` (placeholder)
    - Built packages use the actual tag version (e.g., `1.2.3`)
 
-4. **Automated Release Notes**:
+5. **Automated Release Notes**:
    - GitHub automatically generates release notes based on merged PRs and commits
    - Uses conventional commit patterns to categorize changes
    - Includes contributor acknowledgments and change summaries
@@ -37,10 +42,10 @@ To create a new release:
 ```bash
 # Ensure you're on the main branch and up to date
 git checkout main
-git pull origin main
+git pull --ff-only origin main
 
-# Create and push a release tag (use semantic versioning)
-python scripts/release.py minor
+# Create and push a release tag explicitly
+poetry run release v1.0.0-beta.4
 ```
 
 The release pipeline (`.github/workflows/build-and-publish.yml`) will automatically:
@@ -51,15 +56,23 @@ The release pipeline (`.github/workflows/build-and-publish.yml`) will automatica
 
 ### Release Helper
 
-Use the helper script to bump and push the next tag:
+Use the helper command to create and push an explicit tag:
 
 ```bash
-python scripts/release.py major   # vX.0.0
-python scripts/release.py minor   # v0.X.0
-python scripts/release.py patch   # v0.0.X
+poetry run release v1.2.3
+poetry run release v1.0.0-beta.4
+poetry run release 1.0.0-rc.1     # 'v' prefix is optional
 ```
 
-It finds the latest `v*` tag, computes the next version, creates an annotated tag, and pushes it to `origin`.
+It validates release preconditions (clean tree, on `main`, in sync with `origin/main`,
+`origin/dev` merged into `main`, tag not already present), then creates an annotated tag and pushes it to `origin`.
+
+Useful options:
+
+```bash
+poetry run release v1.0.0-beta.4 --dry-run  # validate only
+poetry run release v1.0.0-beta.4 --yes      # skip confirmation prompt
+```
 
 ### Customizing Release Notes
 
@@ -83,7 +96,6 @@ Before creating a release, ensure the development environment and code quality s
 All maintainers should have the development environment properly configured as described in [CONTRIBUTING.md](CONTRIBUTING.md), including:
 - Poetry for dependency management
 - Pre-commit hooks installed and active
-- Nox for running quality checks
 
 ### Pre-commit Requirements
 **Critical**: Pre-commit hooks must be installed and passing for all commits that will be included in the release. The pre-commit configuration ensures:
@@ -111,14 +123,18 @@ poetry run pre-commit install --hook-type pre-commit --hook-type commit-msg
 ### Code Quality Validation
 Before releasing, run comprehensive quality checks:
 ```bash
-# Run all quality checks
-nox -s lint format typing tests
-
-# Or individual checks
-nox -s tests          # Run test suite
-nox -s lint           # Check code style
-nox -s format         # Auto-fix formatting
-nox -s typing         # Type checking
+# Tests
+poetry run pytest
+
+# Linting
+poetry run ruff check corneto --exclude tests
+
+# Formatting
+poetry run ruff check corneto --exclude tests --fix
+poetry run ruff format corneto --exclude tests
+
+# Type checking
+poetry run pyrefly check corneto
 ```
 
 ## Development Workflow