You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/community/contributing.rst
+71-14Lines changed: 71 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,7 +18,7 @@ There are two primary groups that contribute to Parcels; oceanographers who brin
18
18
19
19
.. note::
20
20
21
-
The first component of this documentation is geared to those new to open source. Already familiar with GitHub and open source? Skip ahead to the `Editing Parcels code`_ section.
21
+
The first component of this documentation is geared to those new to open source. Already familiar with GitHub and open source? Skip ahead to the `Development`_ section.
22
22
23
23
What is open source?
24
24
--------------------
@@ -55,26 +55,85 @@ In the `Projects panel <https://github.com/OceanParcels/parcels/projects?query=i
55
55
56
56
.. _editing-parcels-code:
57
57
58
-
Editing Parcels code
59
-
---------------------
58
+
Development
59
+
-----------
60
60
61
-
Development environment setup
62
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61
+
Environment setup
62
+
~~~~~~~~~~~~~~~~~
63
+
64
+
.. note::
65
+
66
+
Parcels, alongside popular projects like `Xarray <https://github.com/pydata/xarray>`_, uses `Pixi <https://pixi.sh>`_ to manage environments and run developer tooling. Pixi is a modern alternative to Conda and also includes other powerful tooling useful for a project like Parcels (`read more <https://github.com/OceanParcels/Parcels/issues/2205>`_). It is our sole development workflow - we do not offer a Conda development workflow. Give Pixi a try, you won't regret it!
63
67
64
68
To get started contributing to Parcels:
65
69
66
-
- `fork the repo <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository>`_
67
-
- install the developer version of Parcels following `our developer installation instructions <../installation.rst#installation-for-developers>`_
68
-
- but instead of cloning the Parcels repo, you should clone your fork
**Step 2:** `Fork the repository <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository>`_
73
+
74
+
**Step 3:** Clone your fork and ``cd`` into the repository.
75
+
76
+
**Step 4:** Install the Pixi environment
77
+
78
+
.. code-block:: bash
79
+
80
+
pixi install
81
+
82
+
Now you have a development installation of Parcels, as well as a bunch of developer tooling to run tests, check code quality, and build the documentation! Simple as that.
83
+
84
+
Pixi workflows
85
+
~~~~~~~~~~~~~~
86
+
87
+
You can use the following Pixi commands to run common development tasks.
88
+
89
+
**Testing**
90
+
91
+
- ``pixi run tests`` - Run the full test suite using pytest
92
+
- ``pixi run tests-notebooks`` - Run notebook tests (specifically Argo-related examples)
93
+
94
+
95
+
**Documentation**
69
96
70
-
Now you have a cloned repo that you have full control over, and a conda environment where Parcels is installed in an editable mode (i.e., any changes that you make to the Parcels code will take effect when you use that conda environment to run Python code).
97
+
- ``pixi run docs`` - Build the documentation using Sphinx
98
+
- ``pixi run docs-watch`` - Build and auto-rebuild documentation when files change (useful for live editing)
99
+
- ``pixi run docs-linkcheck`` - Check for broken links in the documentation
100
+
101
+
**Code quality**
102
+
103
+
- ``pixi run lint`` - Run pre-commit hooks on all files (includes formatting, linting, and other code quality checks)
104
+
- ``pixi run typing`` - Run mypy type checking on the codebase
105
+
106
+
**Different environments**
107
+
108
+
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:
109
+
110
+
- ``pixi run -e test-py311 tests`` - Run tests using Python 3.11
111
+
- ``pixi run -e test-py312 tests`` - Run tests using Python 3.12
112
+
113
+
The name of the workflow on GitHub contains the command you have to run locally to recreate the workflow - making it super easy to reproduce CI failures locally.
114
+
115
+
**Typical development workflow**
116
+
117
+
1. Make your code changes
118
+
2. Run ``pixi run lint`` to ensure code formatting and style compliance
119
+
3. Run ``pixi run tests`` to verify your changes don't break existing functionality
120
+
4. If you've added new features, run ``pixi run typing`` to check type annotations
121
+
5. If you've modified documentation, run ``pixi run docs`` to build and verify the docs
122
+
123
+
.. tip::
124
+
125
+
You can run ``pixi info`` to see all available environments and ``pixi task list`` to see all available tasks across environments.
126
+
127
+
128
+
Changing code
129
+
~~~~~~~~~~~~~
71
130
72
131
From there:
73
132
74
133
- create a git branch, implement, commit, and push your changes
75
134
- `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.
76
135
77
-
Look at the ``[tool.pixi.tasks]`` section of ``pyproject.toml`` for a list of tasks that are useful for development.
136
+
78
137
79
138
Code guidelines
80
139
~~~~~~~~~~~~~~~
@@ -85,10 +144,8 @@ Code guidelines
85
144
86
145
- Write clear commit messages that explain the changes you've made.
87
146
- Include tests for any new code you write. Tests are implemented using pytest and are located in the ``tests`` directory.
88
-
- Follow the `NumPy docstring conventions <https://numpydoc.readthedocs.io/en/latest/format.html>`_ when adding or modifying docstrings.
89
-
- 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.
90
-
91
-
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.
147
+
- Follow the `NumPy docstring conventions <https://numpydoc.readthedocs.io/en/latest/format.html>`_ when adding or modifying public API docstrings.
148
+
- 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.
Copy file name to clipboardExpand all lines: docs/installation.rst
+1-38Lines changed: 1 addition & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -56,41 +56,4 @@ The steps below are the installation instructions for Linux, macOS and Windows.
56
56
Installation for developers
57
57
===========================
58
58
59
-
Using Miniconda
60
-
---------------
61
-
62
-
If you would prefer to have a development installation of Parcels (i.e., where the code can be actively edited), you can do so by setting up Miniconda (as detailed in step 1 above), cloning the Parcels repo, installing dependencies using the environment file, and then installing Parcels in an editable mode such that changes to the cloned code can be tested during development.
63
-
64
-
**Step 1:** Same as `step 1 above`_.
65
-
66
-
**Step 2:** Clone the Parcels repo and create a new environment with the development dependencies:
**Step 3:** Activate the environment and install Parcels in editable mode:
75
-
76
-
.. code-block:: bash
77
-
78
-
conda activate parcels-dev
79
-
pip install --no-build-isolation --no-deps -e .
80
-
81
-
82
-
Using Pixi
83
-
----------
84
-
For developers who want to use Pixi (a modern alternative to Anaconda - see `"Transitioning from the conda or mamba to pixi" <https://pixi.sh/latest/switching_from/conda/>`_) to manage their development environment, the following steps can be followed:
Now you can use ``pixi run`` for a list of available tasks useful for development, such as running tests, checking code coverage, and building the documentation. You can also do ``pixi shell`` to "activate" the environment (and do ``exit`` to deactivate it). See `here <https://pixi.sh/latest/switching_from/conda/#key-differences-at-a-glance>`_ for a comparison between Pixi and Conda commands.
59
+
See the `development section in our contributing guide <./community/contributing.rst#development>`_ for development instructions.
0 commit comments