-
Notifications
You must be signed in to change notification settings - Fork 168
Closed
Labels
documentationhackathon2025Good issues for the hackathon at the Parcels anniversary event in 2025.Good issues for the hackathon at the Parcels anniversary event in 2025.v4
Description
Following #2244 we need to update our contributing and development installation instructions to mention pixi.
Here is a patch that can be built off of
commit 29376bb2f0c8c0c33139d1cc7c459c56f3cbce93
Author: Vecko <36369090+VeckoTheGecko@users.noreply.github.com>
Date: Fri Sep 26 13:14:12 2025 +0200
WIP pixi contrib
diff --git a/docs/community/contributing.rst b/docs/community/contributing.rst
index 8b11dee3..26409b3b 100644
--- a/docs/community/contributing.rst
+++ b/docs/community/contributing.rst
@@ -74,8 +74,51 @@ From there:
- create a git branch, implement, commit, and push your changes
- `create a pull request <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_ (PR) into ``main`` of the original repo making sure to link to the issue that you are working on. Not yet finished with your feature but still want feedback on how you're going? Then mark it as "draft" and ``@ping`` a maintainer. See our `maintainer notes <maintainer.md>`_ to see our PR review workflow.
+
Look at the ``[tool.pixi.tasks]`` section of ``pyproject.toml`` for a list of tasks that are useful for development.
+Developer workflow
+~~~~~~~~~~~~~~~~~~
+
+Parcels uses `pixi <https://pixi.sh>`_ for environment management as well as running developer tooling. Once you have installed Parcels for development, you can use the following commands to run common development tasks:
+
+**Testing**
+
+- ``pixi run tests`` - Run the full test suite using pytest
+- ``pixi run tests-notebooks`` - Run notebook tests (specifically Argo-related examples)
+
+**Documentation**
+
+- ``pixi run docs`` - Build the documentation using Sphinx
+- ``pixi run docs-watch`` - Build and auto-rebuild documentation when files change (useful for live editing)
+- ``pixi run docs-linkcheck`` - Check for broken links in the documentation
+
+**Code quality**
+
+- ``pixi run lint`` - Run pre-commit hooks on all files (includes formatting, linting, and other code quality checks)
+- ``pixi run typing`` - Run mypy type checking on the codebase
+
+**Different environments**
+
+Parcels supports testing against different environments (e.g., different Python versions) with different feature sets. In CI we test against these environments, and you can too locally. For example:
+
+- ``pixi run -e test-py311 tests`` - Run tests using Python 3.11
+- ``pixi run -e test-py312 tests`` - Run tests using Python 3.12
+
+The name of the workflow on GitHub contains the command you have to run locally to recreate the workflow.
+
+**Typical development workflow**
+
+1. Make your code changes
+2. Run ``pixi run lint`` to ensure code formatting and style compliance
+3. Run ``pixi run tests`` to verify your changes don't break existing functionality
+4. If you've added new features, run ``pixi run typing`` to check type annotations
+5. If you've modified documentation, run ``pixi run docs`` to build and verify the docs
+
+.. tip::
+
+ You can run ``pixi info`` to see all available environments and ``pixi task list`` to see all available tasks across environments.
+
Code guidelines
~~~~~~~~~~~~~~~
@@ -86,9 +129,8 @@ Code guidelines
- Write clear commit messages that explain the changes you've made.
- Include tests for any new code you write. Tests are implemented using pytest and are located in the ``tests`` directory.
- Follow the `NumPy docstring conventions <https://numpydoc.readthedocs.io/en/latest/format.html>`_ when adding or modifying docstrings.
-- Follow the `PEP 8 <https://peps.python.org/pep-0008/>`_ style guide when writing code. This codebase also uses `flake8 <https://flake8.pycqa.org/en/latest/>`_ and `isort <https://pycqa.github.io/isort/>`_ to ensure a consistent code style.
+- Follow the `PEP 8 <https://peps.python.org/pep-0008/>`_ style guide when writing code. This codebase also uses additional tooling to enforce additional style guidelines. You can run this tooling with ``pixi run lint``, and see which tooling is run in the ``.pre-commit-config.yaml`` file.
-If you're comfortable with these code guidelines, and want to enforce them on your local machine before pushing, you can install the Git hooks for the repo by running ``pre-commit install``. This will run tools to check your changes adhere to these guidelines as you make commits.
----
Metadata
Metadata
Assignees
Labels
documentationhackathon2025Good issues for the hackathon at the Parcels anniversary event in 2025.Good issues for the hackathon at the Parcels anniversary event in 2025.v4
Type
Projects
Status
Done
Status
Done