Merge pull request #1696 from OceanParcels/v/docs

Add Parcels versioning/deprecation policies and maintainer docs

.github/workflows/ci.yml

@@ -46,6 +46,7 @@ jobs:
         uses: codecov/codecov-action@v4.5.0
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+        if: matrix.python-version == '3.12'
         with:
           flags: unit-tests
       - name: Upload test results
@@ -91,11 +92,11 @@ jobs:
       - unit-test
       - integration-test
     steps:
-    - name: Merge Artifacts
-      uses: actions/upload-artifact/merge@v4
-      with:
-        name: Testing reports
-        pattern: "* report *"
+      - name: Merge Artifacts
+        uses: actions/upload-artifact/merge@v4
+        with:
+          name: Testing reports
+          pattern: "* report *"
   typechecking:
     name: mypy
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -19,11 +19,11 @@ repos:
         args: [--select, I, --fix]
         types_or: [jupyter]
       - id: ruff-format
-        types_or: [ python, jupyter ]
-  - repo: https://github.com/biomejs/pre-commit
-    rev: v0.4.0
+        types_or: [python, jupyter]
+  - repo: https://github.com/rbubley/mirrors-prettier # Update mirror as official mirror is deprecated
+    rev: v3.3.3
     hooks:
-      - id: biome-format
+      - id: prettier
 
   # Ruff doesn't have full coverage of pydoclint https://github.com/astral-sh/ruff/issues/12434
   - repo: https://github.com/PyCQA/flake8

codecov.yml

@@ -7,11 +7,15 @@ coverage:
       default:
         informational: true
 comment:
-  layout: " diff, flags, files"
-  behavior: default
-  require_changes: true
-  require_base: false
-  require_head: true
-  hide_project_coverage: true
+  false
+  # # Wait until all builds that upload coverage report have completed before commenting on
+  # # the PR with the coverage report.
+  # after_n_builds: 6
+  # layout: " diff, flags, files"
+  # behavior: default
+  # require_changes: true
+  # require_base: false
+  # require_head: true
+  # hide_project_coverage: true
 # When modifying this file, please validate using
 # curl -X POST --data-binary @codecov.yml https://codecov.io/validate

docs/contributing.rst → docs/community/contributing.rst

@@ -41,8 +41,8 @@ Your first contribution
 There are many ways that you can contribute to Parcels. You can:
 
 - Participate in discussion about Parcels, either through the `issues <https://github.com/OceanParcels/parcels/issues>`_ or `discussions <https://github.com/OceanParcels/parcels/discussions>`_ tab
-- Suggest improvements to `tutorials <documentation/index.rst>`_
-- Suggest improvements to `documentation <index.rst>`_
+- Suggest improvements to `tutorials <../documentation/index.rst>`_
+- Suggest improvements to `documentation <../index.rst>`_
 - Write code (fix bugs, implement features, codebase improvements, etc)
 
 All of these require you to make an account on GitHub, so that should be your first step.
@@ -64,22 +64,22 @@ Development environment setup
 To get started contributing to Parcels:
 
 - `fork the repo <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository>`_
-- install the developer version of Parcels following `our developer installation instructions <installation.rst#installation-for-developers>`_
+- install the developer version of Parcels following `our developer installation instructions <../installation.rst#installation-for-developers>`_
     - but instead of cloning the Parcels repo, you should clone your fork
 
 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).
 
 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>`_ into ``master`` of the original repo making sure to link to the issue that you are working on. This can either be done while you're developing (as a draft pull request) so that feedback can be given, or when you think your change is ready to be seen.
+- `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 ``master`` 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.
 
 If you made changes to the documentation, and want to render a local version, you can run the command ``sphinx-autobuild --ignore "*.zip" docs docs/_build`` to create a server to automatically rebuild the documentation when you make changes.
 
 Code guidelines
 ~~~~~~~~~~~~~~~
 
-.. warning::
+.. note::
 
     These guidelines are here to promote Python best practices, as well as standardise the Parcels code. If you're not sure what some of these guidelines mean, don't worry! Your contribution is still appreciated. When you create your pull request, maintainers can modify your code to comply with these guidelines.
 

docs/community/index.rst

@@ -0,0 +1,20 @@
+Community
+=========
+
+These sections contain documentation relevant to the Parcels community.
+See the sections in the primary sidebar and below to explore.
+
+.. toctree::
+    :caption: User documentation
+    :maxdepth: 1
+
+    contributing
+    Versioning and Deprecation Policies <policies>
+
+
+
+.. toctree::
+    :caption: Maintainer documentation
+    :maxdepth: 1
+
+    maintainer

docs/community/maintainer.md

@@ -0,0 +1,31 @@
+# Maintainers notes
+
+> Workflow information mainly relevant to maintainers
+
+## PR review workflow
+
+- Submit a PR (mark as draft if your feature isn't ready yet, but still want to share your work)
+- Request PR to be reviewed by at least one maintainer. Other users are also welcome to submit reviews on PRs.
+- Implement or discuss suggested edits
+- Once PR is approved:
+  - Original author merges the PR (if original author has sufficient permissions)
+  - Wait for maintainer to merge
+  - If more edits are required: Implement edits and re-request review if changes are significant
+- Close linked issue
+
+---
+
+- If PR is automated (i.e., from dependabot or similar), maintainer can review and merge.
+
+## Release checklist
+
+- Go to GitHub, draft new release. Enter name of version and "create new tag" if it doesn't already exist. Click "Generate Release Notes". Currate release notes as needed. Look at a previous version release to match the format (title, header, section organisation etc.)
+- Go to [conda-forge/parcels-feedstock](https://github.com/conda-forge/parcels-feedstock), create new issue with `@conda-forge-admin, please update version`. This will prompt a build, otherwise there can be a delay in the build.
+  - Approve PR and merge on green
+- Update version in `CITATION.cff` file
+- Check "publish to PyPI" workflow succeeded
+- Update oceanparcels.org
+  - Parcels development status
+  - Check feature tiles
+  - Check for broken links on oceanparcels using [this tracking issue](https://github.com/OceanParcels/oceanparcels_website/issues/85)
+- (once package is available on conda) Re-build the Binder

docs/community/policies.md

@@ -0,0 +1,27 @@
+# Policies
+
+Parcels, as of v3.1.0, has adopted versioning and deprecation policies.
+
+## Versioning
+
+Parcels mostly follows [semantic versioning](https://semver.org/), where the version number (e.g., v2.1.0) is thought of as `MAJOR.MINOR.PATCH`.
+
+> MAJOR version for incompatible API changes<br>
+> MINOR version for added functionality in a backward compatible manner<br>
+> PATCH version for backward compatible bug fixes<br>
+
+Parcels doesn't implement strict backwards compatibility between minor versions. We may make small changes that deprecate elements of the codebase (e.g., an obscure parameter that is no longer needed). Such deprecations will follow our deprecation policy.
+
+Note when conducting research we highly recommend documenting which version of Parcels (and other packages) you are using. This can be as easy as doing `conda env export > environment.yml` alongside your project code. The Parcels version used to generate an output file is also stored as metadata entry in the `.zarr` output file.
+
+## Deprecation policy
+
+Deprecations in the Parcels codebase between minor releases will be handled using the following 6-month timeline:
+
+- Functionality is marked for deprecation (e.g., in v2.1.0). This will include a warning to the user, instructions on how to update their scripts, and a note about when the feature will be removed. At this point the functionality still works as before.
+- One minor release later (e.g., in v2.2.0), or at least 3 months later, the functionality will be replaced with `NotImplementedError`.
+- One minor release later (e.g., in v2.3.0), or at least 3 months later, the functionality will be removed entirely.
+
+These changes will be communicated in release notes.
+
+Deprecations of classes or modules between minor releases will be avoided, except in the instance where it is deemed to have little to no impact on the end user (e.g., if the class/module was mistakenly included in the Public API to begin with, and isn't used in any user scripts or tutorial notebooks).

docs/index.rst

@@ -1,5 +1,5 @@
 Parcels documentation
-===================================
+=====================
 
 Welcome to the documentation of Parcels. **Parcels** (Probably A Really Computationally Efficient Lagrangian Simulator) is a set of Python classes and methods to create customisable particle tracking simulations using output from Ocean Circulation models. Parcels can be used to track passive and active particulates such as water, plankton, `plastic <http://www.topios.org/>`_ and `fish <https://github.com/Jacketless/IKAMOANA>`_.
 
@@ -9,7 +9,7 @@ Welcome to the documentation of Parcels. **Parcels** (Probably A Really Computat
 
 Here you'll find `installation instructions <installation.rst>`_, `tutorials and documentation <documentation/index.rst>`_, and the `API reference <reference.rst>`_ for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
 
-If you need more help with Parcels, try the `Discussions page on GitHub <https://github.com/OceanParcels/parcels/discussions>`_. If you think you found a bug, file an `Issue on GitHub <https://github.com/OceanParcels/parcels/issues>`_. If you want to help improve Parcels, see the `Contributing <contributing.rst>`_ page.
+If you need more help with Parcels, try the `Discussions page on GitHub <https://github.com/OceanParcels/parcels/discussions>`_. If you think you found a bug, file an `Issue on GitHub <https://github.com/OceanParcels/parcels/issues>`_. If you want to help improve Parcels, see the `Contributing <community/contributing.rst>`_ page.
 
 .. toctree::
    :maxdepth: 2
@@ -20,5 +20,5 @@ If you need more help with Parcels, try the `Discussions page on GitHub <https:/
    Tutorials & Documentation <documentation/index>
    API reference <reference>
    Release Notes <https://github.com/OceanParcels/Parcels/releases>
-   Contributing <contributing>
+   Contributing <community/index>
    OceanParcels website <https://oceanparcels.org/>

docs/installation.rst

@@ -55,6 +55,7 @@ The steps below are the installation instructions for Linux, macOS and Windows.
     conda activate parcels
 
 
+
 Installation for developers
 ===========================