From 72536c6653f2baa4fdf9377dd16e4559ba5e4f5f Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Sun, 4 Jan 2026 17:24:15 +1100 Subject: [PATCH 01/11] Update Makefile Signed-off-by: Tomas Pereira de Vasconcelos --- Makefile | 5 ++--- docs/reference/changelog.md | 1 + 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 4f867ed6..fff82b13 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,6 @@ VENV_BIN := $(VENV_PATH)/bin OFFLINE ?= 0 ifeq ($(OFFLINE), 1) _UV_OFFLINE_ARG = --offline - else _UV_OFFLINE_ARG = endif @@ -58,7 +57,7 @@ _check-sys: ## Check system requirements fi -$(VENV_PATH): _check-sys ## create a virtual environment +$(VENV_PATH): | _check-sys ## create a virtual environment @echo "==> Creating local virtual environment under: $(VENV_PATH)/ ($(BASE_PYTHON))" @uv venv $(_UV_OFFLINE_ARG) --python="$(BASE_PYTHON)" --seed "$(VENV_PATH)" @@ -78,7 +77,7 @@ install: $(VENV_PATH) ## install all local development dependencies .PHONY: jupyter-init jupyter-init: install ## initialise a jupyter environment @echo "==> Setting up jupyterlab environment..." - @$(VENV_BIN)/uv pip install --upgrade ipykernel jupyter + @uv pip install --upgrade ipykernel jupyter @$(VENV_BIN)/python -m ipykernel install --user --name='ridgeplot' --display-name='ridgeplot' diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 2bd31788..8d0c26ca 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -19,6 +19,7 @@ Unreleased changes ### Developer Experience - Add a basic version of Cursor's `worktrees.json` config ({gh-pr}`364`) +- Small improvements to the project's Makefile ({gh-pr}`???`) ### CI/CD From 1ff61798c602b2faecd5604e5ca7a1b57acd54ae Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Tue, 3 Feb 2026 18:58:39 +1100 Subject: [PATCH 02/11] wip: add AGENTS.md Signed-off-by: Tomas Pereira de Vasconcelos --- .codex/environments/environment.toml | 35 +++ .../RULES.md | 32 +++ .cursor/worktrees.json | 3 +- AGENTS.md | 264 ++++++++++++++++++ MANIFEST.in | 3 +- 5 files changed, 335 insertions(+), 2 deletions(-) create mode 100644 .codex/environments/environment.toml create mode 100644 .cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md create mode 100644 AGENTS.md diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml new file mode 100644 index 00000000..0abaee09 --- /dev/null +++ b/.codex/environments/environment.toml @@ -0,0 +1,35 @@ +# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY +version = 1 +name = "ridgeplot" + +[setup] +script = ''' +if git remote | grep -q '^origin$'; then + echo "info: git remote 'origin' already exists" +else + git remote add origin https://github.com/tpvasconcelos/ridgeplot.git +fi +if git rev-parse --is-shallow-repository 2>/dev/null | grep -q true; then + git fetch --unshallow +else + echo "info: git repository is already complete (not shallow)" +fi +git fetch -v +make init +source .venv/bin/activate +''' + +[[actions]] +name = "source venv" +icon = "tool" +command = "source .venv/bin/activate" + +[[actions]] +name = "tox -m tests" +icon = "test" +command = "tox -m tests" + +[[actions]] +name = "tox -m static-quick" +icon = "test" +command = "tox -m static-quick" diff --git a/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md b/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md new file mode 100644 index 00000000..c0170654 --- /dev/null +++ b/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md @@ -0,0 +1,32 @@ +--- +description: Dropping and/or adding support for Python versions +alwaysApply: false +--- +This project tries to follow the [official](https://devguide.python.org/versions/) Python support policy. + +When a new Python version is released, support for it should be added in the CI pipeline as soon as possible. This means updating `.github/workflows/ci.yml`'s `jobs.software-tests.strategy.matrix.python-version` and `pyproject.toml`'s `project.classifiers` to include the new version. + +When a Python version reaches its end-of-life, support for it should be dropped. This means removing it from the CI pipeline and updating the following entries: + +- `.github/workflows/ci.yml`: + - `jobs.software-tests.strategy.matrix.python-version` + - `jobs.static-checks.steps.with.python-version` +- `.github/workflows/release.yml`: + - `jobs.build.steps.with.python-version` + - `jobs.github-release.steps.with.python-version` +- `.pre-commit-config.yaml`: `default_language_version.python` +- `.readthedocs.yml`: `build.tools.python` +- `AGENTS.md`: Wherever relevant +- `docs/development/contributing.md`: Wherever relevant +- `makefile`: `BASE_PYTHON` +- `mypy.ini`: `python_version` +- `pyproject.toml` + - `project.classifiers` + - `project.requires-python` +- `pyrightconfig.json`: `pythonVersion` +- `ruff.toml`: `target-version` + +In both instances, you should also update `docs/reference/changelog.md` to reflect the change in supported Python versions for the next release. + +- When adding support for a new Python version, you can add an _"Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)"_ entry at the top of the _"Unreleased changes"_ section. +- When dropping support for a Python version, you can add a _"Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)"_ entry in a _"Breaking changes"_ section under the _"Unreleased changes"_ section. diff --git a/.cursor/worktrees.json b/.cursor/worktrees.json index 810d8c0d..e7ab0a01 100644 --- a/.cursor/worktrees.json +++ b/.cursor/worktrees.json @@ -1,5 +1,6 @@ { "setup-worktree": [ - "make init" + "make init", + "source .venv/bin/activate" ] } diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..0ee7b078 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,264 @@ +# ridgeplot Development Guide for AI Agents + +`ridgeplot` is a Python package that provides a simple interface for plotting beautiful and interactive ridgeline plots within the extensive Plotly ecosystem. + +This file provides guidance for AI assistants working with the ridgeplot codebase. + +## Public API Overview + +The library only exposes three public functions to end users. + +Two of these functions are toy dataset loaders (`ridgeplot.datasets.load_probly()` and +`ridgeplot.datasets.load_lincoln_weather()`) but they are not the focus on the project and are only exposed for backwards compatibility reasons. + +The third function (`ridgeplot.ridgeplot()`) is a Plotly Figure ( +`plotly.graph_objects.Figure`) factory function, and it's the focus of this project. See its docstring at +`src/ridgeplot/_ridgeplot.py` for full details. + +## .cursor rules directory + +You can check +`.cursor/rules` before providing recommendations or generating code. This directory contains the authoritative rules for all development aspects. + +To find the relevant rules: + +1. Find ALL .md files in `.cursor/rules` +2. Read ALL relevant rules files, based on the filetypes/languages/libraries/tasks/folders involved (e.g., .tsx, .css, .java, React, + `//web/src/pages/home`, etc) +3. If unsure, read metadata (first 5 lines) of any .mdc file to check rule scope/description/keywords + +**For common tasks, you can check these specific files:** + +- Bazel/testing: `.cursor/rules/bazel-test-execution.mdc` +- Java code: `.cursor/rules/java-conventions.mdc` +- TypeScript/web: `.cursor/rules/web-conventions.mdc` +- Pull requests: `.cursor/rules/pull-request-conventions.mdc` + +**Documentation:** https://ridgeplot.readthedocs.io/en/stable/ + +**Python Version**: Requires Python 3.10+ + +## Common Commands + +### Environment Setup + +```bash +# Initialize full development environment (recommended for first-time setup) +# This creates .venv, installs dependencies, and sets up pre-commit hooks +make init + +# Use a different Python version if needed (default is python3.10) +BASE_PYTHON=python3.14 make init + +# Offline mode (uses cached packages only) - useful when the internet is down +OFFLINE=1 make init + +# Activate the virtual environment +source .venv/bin/activate +``` + +### Running Tests + +```bash +# Run all test suits (unit + e2e + cicd_utils) +tox -m tests + +# Run a specific test suite +tox -e tests-unit # Unit tests with coverage +tox -e tests-e2e # End-to-end tests +tox -e tests-cicd_utils # CI/CD utilities tests + +# Run pytest directly with custom options +tox -e pytest -- tests/unit/test_init.py --no-cov +tox -e pytest -- -k "test_specific_function" --no-cov +``` + +### Linting and Formatting + +```bash +# Run the main static checks +tox -m static-quick + +# Run the entire suite of static checks (incl. all pre-commit hooks) +# If running from the main branch, you'll need +# to skip the 'no-commit-to-branch' check with: +SKIP='no-commit-to-branch' tox -m static + +# Run specific pre-commit hooks +pre-commit run ruff --all-files +pre-commit run ruff-format --all-files + +# Run type checking with pyright only +tox -e typing +``` + +### Documentation + +```bash +# Build static documentation +tox -e docs-static +``` + +## Architecture Overview + +``` +src/ridgeplot/ +├── __init__.py # Public API exports +├── _ridgeplot.py # Main ridgeplot() function +├── _figure_factory.py # Plotly Figure construction +├── _kde.py # Kernel Density Estimation +├── _hist.py # Histogram binning +├── _types.py # Type aliases and type guards +├── _utils.py # Utility functions +├── _missing.py # Sentinel for missing values +├── _version.py # Version string (setuptools-scm) +├── _color/ # Color handling +│ ├── colorscale.py # Colorscale resolution +│ ├── css_colors.py # CSS color parsing +│ ├── interpolation.py # Color interpolation +│ └── utils.py # Color utilities +├── _obj/traces/ # Trace objects +│ ├── area.py # Area trace (filled curves) +│ ├── bar.py # Bar trace (histograms) +│ └── base.py # Base trace class +├── _vendor/ # Vendored dependencies +└── datasets/ # Built-in datasets + └── data/ # CSV data files + +tests/ +├── conftest.py # Shared pytest fixtures +├── unit/ # Unit tests for individual modules +├── e2e/ # End-to-end tests with expected outputs +│ └── artifacts/ # JSON artifacts for e2e comparisons +└── cicd_utils/ # Tests for CI/CD utilities + +cicd_utils/ # CI/CD helper modules +├── cicd/ # Scripts and test helpers +└── ridgeplot_examples/ # Example implementations for docs/testing +``` + +### Key Data Flow + +1. User calls `ridgeplot(samples=...)` or `ridgeplot(densities=...)` +2. If samples provided → KDE (`_kde.py`) or histogram binning (`_hist.py`) produces densities +3. Densities are normalised if `norm` parameter is set +4. `create_ridgeplot()` in `_figure_factory.py` builds the Plotly Figure: + - Resolves colorscale and computes colors for each trace + - Creates trace objects (area or bar) for each density + - Applies layout settings (spacing, padding, axes) +5. Returns a `plotly.graph_objects.Figure` that users can further customise + +### Type System + +The codebase uses extensive type annotations. Key types in `_types.py`: + +- **Samples/Densities**: Ragged 3D arrays `[rows][traces_per_row][values]` +- **ShallowSamples/ShallowDensities**: 2D arrays (one trace per row) +- **ColorScale**: `Collection[tuple[float, Color]]` +- **Type guards**: `is_shallow_samples()`, `is_densities()`, etc. + +## Code Style Guidelines + +### General + +- **Python version**: 3.10+ (uses modern typing features) +- **Line length**: 100 characters +- **Formatting**: Ruff (replaces black, isort, flake8) +- **Imports**: Always include `from __future__ import annotations` +- **Docstrings**: NumPy style +- **Type annotations**: Use full and modern type annotations throughout with strict pyright checking + +### Type Annotations + +- All functions must be fully typed +- Use `TYPE_CHECKING` blocks for import-only types +- Uses **pyright** in strict mode (see `pyrightconfig.json`) +- Use type guards for runtime type narrowing (see `_types.py`) +- Follow this general principle for user-facing code: be contravariant in the input type and covariant in the output type + +## Working with This Codebase + +### When Adding New Features + +1. Start with `_ridgeplot.py` to understand the main entry point +2. Add new parameters following the existing patterns (with proper deprecation handling) +3. Update type annotations in `_types.py` if introducing new data structures +4. Add tests in `tests/unit/` with good coverage +5. Update documentation in docstrings following the existing conventions + +### When Fixing Bugs + +1. Write a failing test first +2. Fix the issue with minimal changes +3. Ensure all existing tests pass +4. Check type annotations are correct + +### Common Patterns + +**Handling deprecated parameters:** + +```python +if deprecated_param is not MISSING: + if new_param is not None: + raise ValueError("Cannot use both...") + warnings.warn("...", DeprecationWarning, stacklevel=2) + new_param = deprecated_param +``` + +**Type narrowing with guards:** + +```python +if is_shallow_samples(samples): + samples = nest_shallow_collection(samples) +samples = cast("Samples", samples) +``` + +**Lazy imports for performance:** + +```python +# Heavy imports inside functions to reduce import time +def _coerce_to_densities(...): + from ridgeplot._kde import estimate_densities # statsmodels is slow to import +``` + +### Testing Tips + +- Use `--no-cov` flag during development for faster test runs +- Run specific tests: `tox -e pytest -- tests/unit/test_ridgeplot.py -k "test_name" --no-cov` +- The `tests/e2e/artifacts/` directory contains expected Plotly Figure JSON for e2e tests +- `conftest.py` patches `fig.show()` to prevent browser windows during tests + +### Key Files to Know + +| File | Purpose | +|------------------------------------|-----------------------------| +| `src/ridgeplot/_ridgeplot.py` | Main `ridgeplot()` function | +| `src/ridgeplot/_figure_factory.py` | Figure construction logic | +| `src/ridgeplot/_types.py` | All type aliases and guards | +| `tests/unit/test_ridgeplot.py` | Core function tests | +| `cicd_utils/ridgeplot_examples/` | Example scripts for docs | +| `tox.ini` | CI environment definitions | +| `ruff.toml` | Linting configuration | + +## CI/CD Pipeline + +Tests run on GitHub Actions across: + +- Python versions: 3.10, 3.11, 3.12, 3.13, 3.14 +- Operating systems: Ubuntu, macOS, Windows + +Coverage is uploaded to Codecov with: + +- Overall: 98% minimum +- Diff coverage: 100% for new code + +## Notes for AI Assistants + +1. **Always run tests** after making changes: `tox -e pytest -- --no-cov` +2. **Check types** with: `tox -e typing` +3. **Format code** with: `pre-commit run ruff-format --all-files` +4. **Respect existing patterns** - this is a mature codebase with consistent style +5. **Don't add unnecessary abstractions** - keep changes minimal and focused +6. **Preserve deprecation warnings** - the library maintains backward compatibility +7. **Update docstrings** when changing function signatures +8. **Use type guards** for runtime type narrowing instead of assertions diff --git a/MANIFEST.in b/MANIFEST.in index 3706215c..39acec04 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -33,7 +33,8 @@ prune docs/api/autogen prune docs/api/public # Misc -recursive-include .cursor *.json +recursive-include .codex *.toml +recursive-include .cursor *.json *.md recursive-include .github *.yml *.yaml recursive-include cicd_utils README.md *.py *.sh recursive-include misc *.py *.ipynb *.txt *.png From 11f7bdc15e801f6fa54dfc9a251eaa8c32e00ea7 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Tue, 3 Feb 2026 19:31:39 +1100 Subject: [PATCH 03/11] Update AGENTS.md Signed-off-by: Tomas Pereira de Vasconcelos --- AGENTS.md | 184 ++++++++++++++++++++++-------------------------------- 1 file changed, 76 insertions(+), 108 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ee7b078..30e9d4aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,44 +1,22 @@ # ridgeplot Development Guide for AI Agents -`ridgeplot` is a Python package that provides a simple interface for plotting beautiful and interactive ridgeline plots within the extensive Plotly ecosystem. +`ridgeplot` is a Python package for beautiful, interactive ridgeline plots built on Plotly. -This file provides guidance for AI assistants working with the ridgeplot codebase. +## Start Here -## Public API Overview +- Read this file first, then the most relevant source file(s). +- Prefer local docs and tests over memory; do not guess behavior. +- If requirements are unclear or risky, ask a concrete question before changing code. -The library only exposes three public functions to end users. +## Stack and Style Constraints -Two of these functions are toy dataset loaders (`ridgeplot.datasets.load_probly()` and -`ridgeplot.datasets.load_lincoln_weather()`) but they are not the focus on the project and are only exposed for backwards compatibility reasons. +- Python >=3.10 +- Plotly graph objects (dependency is `plotly>=5.20`) +- Line length 100, formatting with ruff +- Docstrings are NumPy style +- Type annotations are modern and throughout with strict checking via pyright -The third function (`ridgeplot.ridgeplot()`) is a Plotly Figure ( -`plotly.graph_objects.Figure`) factory function, and it's the focus of this project. See its docstring at -`src/ridgeplot/_ridgeplot.py` for full details. - -## .cursor rules directory - -You can check -`.cursor/rules` before providing recommendations or generating code. This directory contains the authoritative rules for all development aspects. - -To find the relevant rules: - -1. Find ALL .md files in `.cursor/rules` -2. Read ALL relevant rules files, based on the filetypes/languages/libraries/tasks/folders involved (e.g., .tsx, .css, .java, React, - `//web/src/pages/home`, etc) -3. If unsure, read metadata (first 5 lines) of any .mdc file to check rule scope/description/keywords - -**For common tasks, you can check these specific files:** - -- Bazel/testing: `.cursor/rules/bazel-test-execution.mdc` -- Java code: `.cursor/rules/java-conventions.mdc` -- TypeScript/web: `.cursor/rules/web-conventions.mdc` -- Pull requests: `.cursor/rules/pull-request-conventions.mdc` - -**Documentation:** https://ridgeplot.readthedocs.io/en/stable/ - -**Python Version**: Requires Python 3.10+ - -## Common Commands +## Quick Commands ### Environment Setup @@ -50,7 +28,7 @@ make init # Use a different Python version if needed (default is python3.10) BASE_PYTHON=python3.14 make init -# Offline mode (uses cached packages only) - useful when the internet is down +# Offline mode (uses cached packages only) OFFLINE=1 make init # Activate the virtual environment @@ -60,7 +38,7 @@ source .venv/bin/activate ### Running Tests ```bash -# Run all test suits (unit + e2e + cicd_utils) +# Run all test suites (unit + e2e + cicd_utils) tox -m tests # Run a specific test suite @@ -99,7 +77,7 @@ tox -e typing tox -e docs-static ``` -## Architecture Overview +## Project Map ``` src/ridgeplot/ @@ -137,63 +115,68 @@ cicd_utils/ # CI/CD helper modules └── ridgeplot_examples/ # Example implementations for docs/testing ``` -### Key Data Flow +## Public API -1. User calls `ridgeplot(samples=...)` or `ridgeplot(densities=...)` -2. If samples provided → KDE (`_kde.py`) or histogram binning (`_hist.py`) produces densities -3. Densities are normalised if `norm` parameter is set -4. `create_ridgeplot()` in `_figure_factory.py` builds the Plotly Figure: - - Resolves colorscale and computes colors for each trace - - Creates trace objects (area or bar) for each density - - Applies layout settings (spacing, padding, axes) -5. Returns a `plotly.graph_objects.Figure` that users can further customise +The public API exposes one main function: `ridgeplot.ridgeplot(...) -> go.Figure` -### Type System +The `ridgeplot()` docstring in `src/ridgeplot/_ridgeplot.py` contains the API contract. -The codebase uses extensive type annotations. Key types in `_types.py`: +`ridgeplot.datasets.load_probly()` and + `ridgeplot.datasets.load_lincoln_weather()` are legacy loaders kept for + backwards compatibility only. -- **Samples/Densities**: Ragged 3D arrays `[rows][traces_per_row][values]` -- **ShallowSamples/ShallowDensities**: 2D arrays (one trace per row) -- **ColorScale**: `Collection[tuple[float, Color]]` -- **Type guards**: `is_shallow_samples()`, `is_densities()`, etc. +## Key Data Flow -## Code Style Guidelines +1. Users call `ridgeplot(samples=...)` or `ridgeplot(densities=...)`. +2. If samples are provided, KDE in `_kde.py` or histogram binning in `_hist.py` + produces densities. +3. Densities are normalised if the `norm` parameter is set. +4. `create_ridgeplot()` in `_figure_factory.py` builds the Plotly Figure by + resolving colors, creating traces, and applying layout settings. +5. The function returns a `plotly.graph_objects.Figure`. -### General +## Key Files to Know -- **Python version**: 3.10+ (uses modern typing features) -- **Line length**: 100 characters -- **Formatting**: Ruff (replaces black, isort, flake8) -- **Imports**: Always include `from __future__ import annotations` -- **Docstrings**: NumPy style -- **Type annotations**: Use full and modern type annotations throughout with strict pyright checking +| File | Purpose | +|------------------------------------|-----------------------------| +| `src/ridgeplot/_ridgeplot.py` | Main `ridgeplot()` function | +| `src/ridgeplot/_figure_factory.py` | Figure construction logic | +| `src/ridgeplot/_types.py` | All type aliases and guards | +| `tests/unit/test_ridgeplot.py` | Core function tests | +| `cicd_utils/ridgeplot_examples/` | Example scripts for docs | +| `docs/` | User and developer docs | +| `tox.ini` | CI environment definitions | +| `ruff.toml` | Linting configuration | -### Type Annotations +Documentation: https://ridgeplot.readthedocs.io/en/stable/ -- All functions must be fully typed -- Use `TYPE_CHECKING` blocks for import-only types -- Uses **pyright** in strict mode (see `pyrightconfig.json`) -- Use type guards for runtime type narrowing (see `_types.py`) -- Follow this general principle for user-facing code: be contravariant in the input type and covariant in the output type - -## Working with This Codebase +## Workflow Expectations ### When Adding New Features -1. Start with `_ridgeplot.py` to understand the main entry point -2. Add new parameters following the existing patterns (with proper deprecation handling) -3. Update type annotations in `_types.py` if introducing new data structures -4. Add tests in `tests/unit/` with good coverage -5. Update documentation in docstrings following the existing conventions +1. Start with `src/ridgeplot/_ridgeplot.py` to understand the entry point. +2. Add parameters following existing patterns and deprecation handling. +3. Update types in `src/ridgeplot/_types.py` when introducing new structures. +4. Add tests in `tests/unit/` with good coverage. +5. Update docstrings to match the new behavior. ### When Fixing Bugs -1. Write a failing test first -2. Fix the issue with minimal changes -3. Ensure all existing tests pass -4. Check type annotations are correct +1. Write a failing test first. +2. Fix the issue with minimal changes. +3. Ensure tests and type checks pass. +4. Verify docstrings remain accurate. -### Common Patterns +### Type Annotations + +- Uses **pyright** in strict mode (see `pyrightconfig.json`) +- All functions must be fully typed, following modern Python typing practices and existing project conventions. +- Use `TYPE_CHECKING` blocks for import-only types +- Use type guards for runtime type narrowing (see `_types.py`) +- Follow this general principle for user-facing code: be contravariant in the input type and covariant in the output type +- Add type aliases close to their usage. If widely used, place in `_types.py`. + +## Common Patterns **Handling deprecated parameters:** @@ -221,44 +204,29 @@ def _coerce_to_densities(...): from ridgeplot._kde import estimate_densities # statsmodels is slow to import ``` -### Testing Tips +## Testing Notes - Use `--no-cov` flag during development for faster test runs -- Run specific tests: `tox -e pytest -- tests/unit/test_ridgeplot.py -k "test_name" --no-cov` +- Run targeted tests via: `tox -e pytest -- tests/unit/test_foo.py -k "test_bar" --no-cov` - The `tests/e2e/artifacts/` directory contains expected Plotly Figure JSON for e2e tests -- `conftest.py` patches `fig.show()` to prevent browser windows during tests -### Key Files to Know +## .cursor Rules -| File | Purpose | -|------------------------------------|-----------------------------| -| `src/ridgeplot/_ridgeplot.py` | Main `ridgeplot()` function | -| `src/ridgeplot/_figure_factory.py` | Figure construction logic | -| `src/ridgeplot/_types.py` | All type aliases and guards | -| `tests/unit/test_ridgeplot.py` | Core function tests | -| `cicd_utils/ridgeplot_examples/` | Example scripts for docs | -| `tox.ini` | CI environment definitions | -| `ruff.toml` | Linting configuration | +Check `.cursor/rules` before changing platform or version support. The only +current rule is for adding or dropping Python versions at +`.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md`. ## CI/CD Pipeline -Tests run on GitHub Actions across: - -- Python versions: 3.10, 3.11, 3.12, 3.13, 3.14 -- Operating systems: Ubuntu, macOS, Windows - -Coverage is uploaded to Codecov with: - -- Overall: 98% minimum -- Diff coverage: 100% for new code +GitHub Actions runs tests on Python 3.10–3.14 across Ubuntu, macOS, and Windows. +Codecov minimums are 98% overall and 100% diff coverage for new code. ## Notes for AI Assistants -1. **Always run tests** after making changes: `tox -e pytest -- --no-cov` -2. **Check types** with: `tox -e typing` -3. **Format code** with: `pre-commit run ruff-format --all-files` -4. **Respect existing patterns** - this is a mature codebase with consistent style -5. **Don't add unnecessary abstractions** - keep changes minimal and focused -6. **Preserve deprecation warnings** - the library maintains backward compatibility -7. **Update docstrings** when changing function signatures -8. **Use type guards** for runtime type narrowing instead of assertions +1. Run tests after changes when feasible, starting with the smallest relevant + subset. +2. Run `tox -e typing` if types are touched or errors are likely. +3. Run `pre-commit run ruff-format --all-files` to format code. +4. Preserve deprecation behavior and public API stability. +5. Keep changes minimal and aligned with existing patterns. +6. Respect existing patterns - this is a mature codebase with consistent style. From 864f2bfbd30fcae4d03367105b9373280a7cd2f8 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Tue, 3 Feb 2026 19:36:44 +1100 Subject: [PATCH 04/11] update changelog.md Signed-off-by: Tomas Pereira de Vasconcelos --- docs/reference/changelog.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md index 8d0c26ca..32a23ef6 100644 --- a/docs/reference/changelog.md +++ b/docs/reference/changelog.md @@ -18,8 +18,9 @@ Unreleased changes ### Developer Experience +- Add AGENTS.md, CLAUDE.md, .codex/, and .cursor/ helper files for AI-assisted development ({gh-pr}`367`) +- Small improvements to the project's Makefile ({gh-pr}`367`) - Add a basic version of Cursor's `worktrees.json` config ({gh-pr}`364`) -- Small improvements to the project's Makefile ({gh-pr}`???`) ### CI/CD From 948e6532210489226ecf2aa6c6e11491aaa9c53b Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Tue, 3 Feb 2026 19:38:32 +1100 Subject: [PATCH 05/11] Add CLAUDE.md Signed-off-by: Tomas Pereira de Vasconcelos --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) create mode 120000 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000..47dc3e3d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From d8280c18bc0b61de434caba725190379c8bb8a14 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Tue, 3 Feb 2026 23:01:48 +1100 Subject: [PATCH 06/11] Update agent skills Signed-off-by: Tomas Pereira de Vasconcelos --- .../RULES.md | 32 ------------------- AGENTS.md | 7 ++-- MANIFEST.in | 1 + .../SKILL.md | 31 ++++++++++++++++++ 4 files changed, 35 insertions(+), 36 deletions(-) delete mode 100644 .cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md create mode 100644 skills/dropping-and-or-adding-support-for-python-versions/SKILL.md diff --git a/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md b/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md deleted file mode 100644 index c0170654..00000000 --- a/.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: Dropping and/or adding support for Python versions -alwaysApply: false ---- -This project tries to follow the [official](https://devguide.python.org/versions/) Python support policy. - -When a new Python version is released, support for it should be added in the CI pipeline as soon as possible. This means updating `.github/workflows/ci.yml`'s `jobs.software-tests.strategy.matrix.python-version` and `pyproject.toml`'s `project.classifiers` to include the new version. - -When a Python version reaches its end-of-life, support for it should be dropped. This means removing it from the CI pipeline and updating the following entries: - -- `.github/workflows/ci.yml`: - - `jobs.software-tests.strategy.matrix.python-version` - - `jobs.static-checks.steps.with.python-version` -- `.github/workflows/release.yml`: - - `jobs.build.steps.with.python-version` - - `jobs.github-release.steps.with.python-version` -- `.pre-commit-config.yaml`: `default_language_version.python` -- `.readthedocs.yml`: `build.tools.python` -- `AGENTS.md`: Wherever relevant -- `docs/development/contributing.md`: Wherever relevant -- `makefile`: `BASE_PYTHON` -- `mypy.ini`: `python_version` -- `pyproject.toml` - - `project.classifiers` - - `project.requires-python` -- `pyrightconfig.json`: `pythonVersion` -- `ruff.toml`: `target-version` - -In both instances, you should also update `docs/reference/changelog.md` to reflect the change in supported Python versions for the next release. - -- When adding support for a new Python version, you can add an _"Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)"_ entry at the top of the _"Unreleased changes"_ section. -- When dropping support for a Python version, you can add a _"Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)"_ entry in a _"Breaking changes"_ section under the _"Unreleased changes"_ section. diff --git a/AGENTS.md b/AGENTS.md index 30e9d4aa..5dcba59f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -210,11 +210,10 @@ def _coerce_to_densities(...): - Run targeted tests via: `tox -e pytest -- tests/unit/test_foo.py -k "test_bar" --no-cov` - The `tests/e2e/artifacts/` directory contains expected Plotly Figure JSON for e2e tests -## .cursor Rules +## Agent Skills -Check `.cursor/rules` before changing platform or version support. The only -current rule is for adding or dropping Python versions at -`.cursor/rules/dropping-and-or-adding-support-for-python-versions/RULES.md`. +Agent skills live under `skills/`. For Python version support changes, follow +`skills/dropping-and-or-adding-support-for-python-versions/SKILL.md`. ## CI/CD Pipeline diff --git a/MANIFEST.in b/MANIFEST.in index 39acec04..28a0eeca 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -39,6 +39,7 @@ recursive-include .github *.yml *.yaml recursive-include cicd_utils README.md *.py *.sh recursive-include misc *.py *.ipynb *.txt *.png recursive-include requirements *.txt +recursive-include skills *.md recursive-include tests *.py recursive-include tests/e2e/artifacts *.json diff --git a/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md b/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md new file mode 100644 index 00000000..cd3a7246 --- /dev/null +++ b/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md @@ -0,0 +1,31 @@ +--- +name: dropping-and-or-adding-support-for-python-versions +description: Update supported Python versions across CI, configs, and docs in line with the official Python support policy. Use when adding or dropping Python version support. +--- +This project follows the official Python support policy: https://devguide.python.org/versions/ + +When adding support for a new Python version +1. Update `.github/workflows/ci.yml` at `jobs.software-tests.strategy.matrix.python-version`. +2. Update `pyproject.toml` at `project.classifiers`. +3. Update `docs/reference/changelog.md` at the top of "Unreleased changes" with: + "Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". + +When dropping support for an end-of-life Python version +1. Remove it from the CI pipeline and update the entries listed below. +2. Update `docs/reference/changelog.md` under an "Unreleased changes" -> "Breaking changes" section with: + "Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". + +Files to update when dropping support for a Python version +- `.github/workflows/ci.yml`: `jobs.software-tests.strategy.matrix.python-version`, + `jobs.static-checks.steps.with.python-version`. +- `.github/workflows/release.yml`: `jobs.build.steps.with.python-version`, + `jobs.github-release.steps.with.python-version`. +- `.pre-commit-config.yaml`: `default_language_version.python`. +- `.readthedocs.yml`: `build.tools.python`. +- `AGENTS.md`: wherever relevant. +- `docs/development/contributing.md`: wherever relevant. +- `Makefile`: `BASE_PYTHON`. +- `mypy.ini`: `python_version`. +- `pyproject.toml`: `project.classifiers`, `project.requires-python`. +- `pyrightconfig.json`: `pythonVersion`. +- `ruff.toml`: `target-version`. From a96953d4d3e0e2a18e02fc23d9ded2d0d21faf80 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Wed, 4 Feb 2026 00:10:09 +1100 Subject: [PATCH 07/11] Update AGENTS.md to use `uvx` Signed-off-by: Tomas Pereira de Vasconcelos --- .codex/environments/environment.toml | 8 ++-- AGENTS.md | 41 +++++++------------ .../SKILL.md | 31 -------------- 3 files changed, 19 insertions(+), 61 deletions(-) delete mode 100644 skills/dropping-and-or-adding-support-for-python-versions/SKILL.md diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml index 0abaee09..fa7c1d5c 100644 --- a/.codex/environments/environment.toml +++ b/.codex/environments/environment.toml @@ -9,14 +9,14 @@ if git remote | grep -q '^origin$'; then else git remote add origin https://github.com/tpvasconcelos/ridgeplot.git fi + if git rev-parse --is-shallow-repository 2>/dev/null | grep -q true; then git fetch --unshallow else echo "info: git repository is already complete (not shallow)" fi + git fetch -v -make init -source .venv/bin/activate ''' [[actions]] @@ -27,9 +27,9 @@ command = "source .venv/bin/activate" [[actions]] name = "tox -m tests" icon = "test" -command = "tox -m tests" +command = "uvx tox -m tests" [[actions]] name = "tox -m static-quick" icon = "test" -command = "tox -m static-quick" +command = "uvx tox -m static-quick" diff --git a/AGENTS.md b/AGENTS.md index 5dcba59f..c6b58600 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,12 +25,6 @@ # This creates .venv, installs dependencies, and sets up pre-commit hooks make init -# Use a different Python version if needed (default is python3.10) -BASE_PYTHON=python3.14 make init - -# Offline mode (uses cached packages only) -OFFLINE=1 make init - # Activate the virtual environment source .venv/bin/activate ``` @@ -39,42 +33,42 @@ source .venv/bin/activate ```bash # Run all test suites (unit + e2e + cicd_utils) -tox -m tests +uvx tox -m tests # Run a specific test suite -tox -e tests-unit # Unit tests with coverage -tox -e tests-e2e # End-to-end tests -tox -e tests-cicd_utils # CI/CD utilities tests +uvx tox -e tests-unit # Unit tests with coverage +uvx tox -e tests-e2e # End-to-end tests +uvx tox -e tests-cicd_utils # CI/CD utilities tests # Run pytest directly with custom options -tox -e pytest -- tests/unit/test_init.py --no-cov -tox -e pytest -- -k "test_specific_function" --no-cov +uvx tox -e pytest -- tests/unit/test_init.py --no-cov +uvx tox -e pytest -- -k "test_specific_function" --no-cov ``` ### Linting and Formatting ```bash # Run the main static checks -tox -m static-quick +uvx tox -m static-quick # Run the entire suite of static checks (incl. all pre-commit hooks) # If running from the main branch, you'll need # to skip the 'no-commit-to-branch' check with: -SKIP='no-commit-to-branch' tox -m static +SKIP='no-commit-to-branch' uvx tox -m static # Run specific pre-commit hooks -pre-commit run ruff --all-files -pre-commit run ruff-format --all-files +uvx pre-commit run ruff --all-files +uvx pre-commit run ruff-format --all-files # Run type checking with pyright only -tox -e typing +uvx tox -e typing ``` ### Documentation ```bash # Build static documentation -tox -e docs-static +uvx tox -e docs-static ``` ## Project Map @@ -207,14 +201,9 @@ def _coerce_to_densities(...): ## Testing Notes - Use `--no-cov` flag during development for faster test runs -- Run targeted tests via: `tox -e pytest -- tests/unit/test_foo.py -k "test_bar" --no-cov` +- Run targeted tests via: `uvx tox -e pytest -- tests/unit/test_foo.py -k "test_bar" --no-cov` - The `tests/e2e/artifacts/` directory contains expected Plotly Figure JSON for e2e tests -## Agent Skills - -Agent skills live under `skills/`. For Python version support changes, follow -`skills/dropping-and-or-adding-support-for-python-versions/SKILL.md`. - ## CI/CD Pipeline GitHub Actions runs tests on Python 3.10–3.14 across Ubuntu, macOS, and Windows. @@ -224,8 +213,8 @@ Codecov minimums are 98% overall and 100% diff coverage for new code. 1. Run tests after changes when feasible, starting with the smallest relevant subset. -2. Run `tox -e typing` if types are touched or errors are likely. -3. Run `pre-commit run ruff-format --all-files` to format code. +2. Run `uvx tox -e typing` if types are touched or errors are likely. +3. Run `uvx pre-commit run ruff-format --all-files` to format code. 4. Preserve deprecation behavior and public API stability. 5. Keep changes minimal and aligned with existing patterns. 6. Respect existing patterns - this is a mature codebase with consistent style. diff --git a/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md b/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md deleted file mode 100644 index cd3a7246..00000000 --- a/skills/dropping-and-or-adding-support-for-python-versions/SKILL.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -name: dropping-and-or-adding-support-for-python-versions -description: Update supported Python versions across CI, configs, and docs in line with the official Python support policy. Use when adding or dropping Python version support. ---- -This project follows the official Python support policy: https://devguide.python.org/versions/ - -When adding support for a new Python version -1. Update `.github/workflows/ci.yml` at `jobs.software-tests.strategy.matrix.python-version`. -2. Update `pyproject.toml` at `project.classifiers`. -3. Update `docs/reference/changelog.md` at the top of "Unreleased changes" with: - "Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". - -When dropping support for an end-of-life Python version -1. Remove it from the CI pipeline and update the entries listed below. -2. Update `docs/reference/changelog.md` under an "Unreleased changes" -> "Breaking changes" section with: - "Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". - -Files to update when dropping support for a Python version -- `.github/workflows/ci.yml`: `jobs.software-tests.strategy.matrix.python-version`, - `jobs.static-checks.steps.with.python-version`. -- `.github/workflows/release.yml`: `jobs.build.steps.with.python-version`, - `jobs.github-release.steps.with.python-version`. -- `.pre-commit-config.yaml`: `default_language_version.python`. -- `.readthedocs.yml`: `build.tools.python`. -- `AGENTS.md`: wherever relevant. -- `docs/development/contributing.md`: wherever relevant. -- `Makefile`: `BASE_PYTHON`. -- `mypy.ini`: `python_version`. -- `pyproject.toml`: `project.classifiers`, `project.requires-python`. -- `pyrightconfig.json`: `pythonVersion`. -- `ruff.toml`: `target-version`. From f38b25269dea5f88f4603a31afc77a21234d7da9 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Wed, 4 Feb 2026 00:49:36 +1100 Subject: [PATCH 08/11] Update skills Signed-off-by: Tomas Pereira de Vasconcelos --- .../SKILL.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 skills/dropping-and-adding-support-for-python-versions/SKILL.md diff --git a/skills/dropping-and-adding-support-for-python-versions/SKILL.md b/skills/dropping-and-adding-support-for-python-versions/SKILL.md new file mode 100644 index 00000000..3a3ca3a8 --- /dev/null +++ b/skills/dropping-and-adding-support-for-python-versions/SKILL.md @@ -0,0 +1,43 @@ +--- +name: dropping-and-adding-support-for-python-versions +description: "Use when adding or dropping Python version support by updating the supported Python versions across CI, configs, and docs in line with the official Python support policy." +--- + +# Dropping and adding support for Python versions + +## Overview + +This project adheres to the official Python support policy: https://devguide.python.org/versions/ + +Use this skill to keep Python version support in sync with the official Python support policy by updating the project files consistently. + +## Workflow + +1. Identify the change type: add support for a new Python version or drop support for an end-of-life Python version. +2. Confirm the exact Python version string (e.g., add support for 3.45) and the PR number to insert in the changelog entry (e.g., PR #1234) +3. Apply the relevant changelog entry and file updates listed below. + +## Adding support for a new Python version + +1. Update `docs/reference/changelog.md` at the top of "Unreleased changes" with: + > Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". +2. Update the following locations: + - .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` + - pyproject.toml: `project.classifiers` + +## Dropping support for an end-of-life Python version + +1. Update `docs/reference/changelog.md` under "Unreleased changes" -> "Breaking changes" with: + > Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`). +2. Update the following locations: + - .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` and `jobs.static-checks.steps.with.python-version` + - .github/workflows/release.yml: `jobs.build.steps.with.python-version` and `jobs.github-release.steps.with.python-version` + - .pre-commit-config.yaml: `default_language_version.python` + - .readthedocs.yml: `build.tools.python` + - AGENTS.md: wherever relevant + - docs/development/contributing.md: wherever relevant + - Makefile: `BASE_PYTHON` + - mypy.ini: `python_version` + - pyproject.toml: `project.classifiers`, `project.requires-python` + - pyrightconfig.json: `pythonVersion` + - ruff.toml: `target-version` From a2bd48dfb9e89f2ffd5bbaa2438c88f84989f5b7 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Wed, 4 Feb 2026 09:11:30 +1100 Subject: [PATCH 09/11] Update SKILL.md and symlink skills/ directories Signed-off-by: Tomas Pereira de Vasconcelos --- .claude/skills | 1 + .codex/skills | 1 + .cursor/skills | 1 + MANIFEST.in | 6 +- .../SKILL.md | 82 +++++++++++++------ 5 files changed, 64 insertions(+), 27 deletions(-) create mode 120000 .claude/skills create mode 120000 .codex/skills create mode 120000 .cursor/skills diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 00000000..42c5394a --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/.codex/skills b/.codex/skills new file mode 120000 index 00000000..42c5394a --- /dev/null +++ b/.codex/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/.cursor/skills b/.cursor/skills new file mode 120000 index 00000000..42c5394a --- /dev/null +++ b/.cursor/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file diff --git a/MANIFEST.in b/MANIFEST.in index 28a0eeca..c9a6bc30 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -33,7 +33,11 @@ prune docs/api/autogen prune docs/api/public # Misc -recursive-include .codex *.toml +include .claude/skills +include .codex/skills +include .cursor/skills +recursive-include .claude *.md +recursive-include .codex *.toml *.md recursive-include .cursor *.json *.md recursive-include .github *.yml *.yaml recursive-include cicd_utils README.md *.py *.sh diff --git a/skills/dropping-and-adding-support-for-python-versions/SKILL.md b/skills/dropping-and-adding-support-for-python-versions/SKILL.md index 3a3ca3a8..136402d4 100644 --- a/skills/dropping-and-adding-support-for-python-versions/SKILL.md +++ b/skills/dropping-and-adding-support-for-python-versions/SKILL.md @@ -1,43 +1,73 @@ --- name: dropping-and-adding-support-for-python-versions -description: "Use when adding or dropping Python version support by updating the supported Python versions across CI, configs, and docs in line with the official Python support policy." +description: "Keeps supported Python versions aligned across CI, configs, and docs. Use when adding a new Python version or dropping an end-of-life version per the official Python support policy." --- # Dropping and adding support for Python versions -## Overview +## When to use -This project adheres to the official Python support policy: https://devguide.python.org/versions/ +- The user asks to add support for a specific Python version. +- The user asks to drop or deprecate an end-of-life Python version. +- The user asks to sync supported versions with the official [Python support policy](https://devguide.python.org/versions/). -Use this skill to keep Python version support in sync with the official Python support policy by updating the project files consistently. +## Required inputs + +- Change type: add or drop a specific version, or asked to sync with the official support policy. +- Exact Python version string (e.g., 3.13), if applicable. + +If any input is missing, ask before editing. ## Workflow -1. Identify the change type: add support for a new Python version or drop support for an end-of-life Python version. -2. Confirm the exact Python version string (e.g., add support for 3.45) and the PR number to insert in the changelog entry (e.g., PR #1234) -3. Apply the relevant changelog entry and file updates listed below. +1. Confirm that you have the required inputs. +2. Apply the file updates for the change type. +3. Add an entry to the [changelog](docs/reference/changelog.md) as specified below. +4. Search for other mentions of the target version and update only those that describe supported versions. +5. Run the entire test suite to ensure no regressions. +6. Run all linters and type checks to ensure consistency. +7. Report the changes made, tests run, and any follow-ups needed. ## Adding support for a new Python version -1. Update `docs/reference/changelog.md` at the top of "Unreleased changes" with: - > Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`)". -2. Update the following locations: - - .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` - - pyproject.toml: `project.classifiers` +- .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` +- pyproject.toml: `project.classifiers` + +Finally, update the changelog at the top of "Unreleased changes" using the following template: + +> Add support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`). ## Dropping support for an end-of-life Python version -1. Update `docs/reference/changelog.md` under "Unreleased changes" -> "Breaking changes" with: - > Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`). -2. Update the following locations: - - .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` and `jobs.static-checks.steps.with.python-version` - - .github/workflows/release.yml: `jobs.build.steps.with.python-version` and `jobs.github-release.steps.with.python-version` - - .pre-commit-config.yaml: `default_language_version.python` - - .readthedocs.yml: `build.tools.python` - - AGENTS.md: wherever relevant - - docs/development/contributing.md: wherever relevant - - Makefile: `BASE_PYTHON` - - mypy.ini: `python_version` - - pyproject.toml: `project.classifiers`, `project.requires-python` - - pyrightconfig.json: `pythonVersion` - - ruff.toml: `target-version` +- .github/workflows/ci.yml: `jobs.software-tests.strategy.matrix.python-version` and `jobs.static-checks.steps.with.python-version` +- .github/workflows/release.yml: `jobs.build.steps.with.python-version` and `jobs.github-release.steps.with.python-version` +- .pre-commit-config.yaml: `default_language_version.python` +- .readthedocs.yml: `build.tools.python` +- AGENTS.md: wherever relevant +- docs/development/contributing.md: wherever relevant +- Makefile: `BASE_PYTHON` +- mypy.ini: `python_version` +- pyproject.toml: `project.classifiers`, `project.requires-python` +- pyrightconfig.json: `pythonVersion` +- ruff.toml: `target-version` + +Finally, update the changelog under "Unreleased changes" -> "Breaking changes" using the following template: + +> Dropped support for Python 3.XX, in accordance with the official Python support policy[^1] ({gh-pr}`XXX`). + +## Validation checks + +- CI matrix, classifiers, and `requires-python` are consistent. +- Tooling configs reflect the new minimum version when dropping support. +- Docs mention the updated supported versions where appropriate. + +## Out of scope + +- Do not change dependency versions or code behavior unless the user asks. +- Do not update unrelated CI jobs or tooling settings. + +## Output + +- Summarize changes and list updated files. +- Note any tests run and follow-ups needed. +- If you encountered any discrepancies between these instructions and the locations in the codebase where supported Python versions are mentioned and need to be updated, please document them here for future reference. From 18c4cc0b0403234a753362579e6f2e27539a3031 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Wed, 4 Feb 2026 10:12:17 +1100 Subject: [PATCH 10/11] Fix issue with agentic skills in MANIFEST.in Signed-off-by: Tomas Pereira de Vasconcelos --- AGENTS.md | 7 ++++--- MANIFEST.in | 3 --- pyproject.toml | 10 ++++++++++ 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c6b58600..02e9b1e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,8 +56,10 @@ uvx tox -m static-quick # to skip the 'no-commit-to-branch' check with: SKIP='no-commit-to-branch' uvx tox -m static +# Run all pre-commit hooks on all files +uvx pre-commit run --all-files + # Run specific pre-commit hooks -uvx pre-commit run ruff --all-files uvx pre-commit run ruff-format --all-files # Run type checking with pyright only @@ -211,8 +213,7 @@ Codecov minimums are 98% overall and 100% diff coverage for new code. ## Notes for AI Assistants -1. Run tests after changes when feasible, starting with the smallest relevant - subset. +1. Run tests after changes when feasible, starting with the smallest relevant subset. 2. Run `uvx tox -e typing` if types are touched or errors are likely. 3. Run `uvx pre-commit run ruff-format --all-files` to format code. 4. Preserve deprecation behavior and public API stability. diff --git a/MANIFEST.in b/MANIFEST.in index c9a6bc30..37d01270 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -33,9 +33,6 @@ prune docs/api/autogen prune docs/api/public # Misc -include .claude/skills -include .codex/skills -include .cursor/skills recursive-include .claude *.md recursive-include .codex *.toml *.md recursive-include .cursor *.json *.md diff --git a/pyproject.toml b/pyproject.toml index 7264cd54..75c5acbc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,3 +66,13 @@ namespaces = false # and we want to push X.devM to TestPyPi # on every merge to the `main` branch local_scheme = "no-local-version" + +[tool.check-manifest] +ignore = [ + ".claude/skills", + ".claude/skills/**", + ".codex/skills", + ".codex/skills/**", + ".cursor/skills", + ".cursor/skills/**", +] From aaf87aacb01b109599da83f4d88390344b59b149 Mon Sep 17 00:00:00 2001 From: Tomas Pereira de Vasconcelos Date: Wed, 4 Feb 2026 10:25:09 +1100 Subject: [PATCH 11/11] Update code blocks Signed-off-by: Tomas Pereira de Vasconcelos --- AGENTS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 02e9b1e2..0c5010e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ ### Environment Setup -```bash +```shell # Initialize full development environment (recommended for first-time setup) # This creates .venv, installs dependencies, and sets up pre-commit hooks make init @@ -31,7 +31,7 @@ source .venv/bin/activate ### Running Tests -```bash +```shell # Run all test suites (unit + e2e + cicd_utils) uvx tox -m tests @@ -47,7 +47,7 @@ uvx tox -e pytest -- -k "test_specific_function" --no-cov ### Linting and Formatting -```bash +```shell # Run the main static checks uvx tox -m static-quick @@ -68,14 +68,14 @@ uvx tox -e typing ### Documentation -```bash +```shell # Build static documentation uvx tox -e docs-static ``` ## Project Map -``` +```text src/ridgeplot/ ├── __init__.py # Public API exports ├── _ridgeplot.py # Main ridgeplot() function