From 3d6f9a946c93c412d73f958fe0f7426ecebe2acd Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Wed, 11 Feb 2026 15:10:55 +0100 Subject: [PATCH 1/7] Update feature request issue template --- .github/ISSUE_TEMPLATE/01_feature.md | 7 ---- .github/ISSUE_TEMPLATE/01_feature.yml | 59 +++++++++++++++++++++++++++ 2 files changed, 59 insertions(+), 7 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/01_feature.md create mode 100644 .github/ISSUE_TEMPLATE/01_feature.yml diff --git a/.github/ISSUE_TEMPLATE/01_feature.md b/.github/ISSUE_TEMPLATE/01_feature.md deleted file mode 100644 index f2765122fa..0000000000 --- a/.github/ISSUE_TEMPLATE/01_feature.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: 🔼 Parcels feature requests, and other enhancements -about: Suggest an improvement to the parcels codebase. -title: "" -labels: ["needs-triage"] -assignees: "" ---- diff --git a/.github/ISSUE_TEMPLATE/01_feature.yml b/.github/ISSUE_TEMPLATE/01_feature.yml new file mode 100644 index 0000000000..7b7b6449e2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_feature.yml @@ -0,0 +1,59 @@ +name: 🔼 Parcels feature requests, and other enhancements +description: Suggest an improvement to the Parcels codebase +labels: ["needs-triage"] +body: + - type: input + id: version + attributes: + label: What version of Parcels are you running? + description: | + Please specify the version of Parcels you're currently using (e.g., v3.1.4, main branch, or commit hash). Put "N/A" if not applicable (e.g., for a documentation suggestion). + placeholder: e.g., v3.1.4 + validations: + required: true + - type: textarea + id: problem + attributes: + label: Is your feature request related to a problem? + description: | + Please do a quick search of existing issues to make sure that this feature request has not been asked before. + + Provide a clear and concise description of what the problem is. For example: + - "I'm trying to simulate particle behavior with [specific physics], but Parcels doesn't support..." + - "When working with [specific data format/kernel], I find it difficult to..." + validations: + required: true + - type: textarea + id: solution + attributes: + label: Describe the solution you'd like + description: | + A clear and concise description of what you want to happen. Include details about: + - How you envision using this feature in your Parcels simulations + - What the API or interface might look like + - Any specific use cases or scientific applications this would enable + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Describe alternatives you've considered + description: | + A clear and concise description of any alternative solutions or features you've considered. For example: + - Workarounds you're currently using + - Other ocean/particle modeling tools that have this feature + - Different approaches to solving the same problem + validations: + required: false + - type: textarea + id: additional-context + attributes: + label: Additional context + description: | + Add any other context about the feature request here. This might include: + - Links to relevant scientific papers or methods + - Example code snippets showing how you'd like to use this feature + - Screenshots or diagrams illustrating the concept + - Information about your use case or research domain + validations: + required: false From 4f79807c3e7e245dbfc0c8c78afa7df57af2a0bb Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Thu, 12 Feb 2026 13:08:13 +0100 Subject: [PATCH 2/7] Add instructions on posting dataset metadata --- .github/ISSUE_TEMPLATE/01_feature.yml | 2 + .github/ISSUE_TEMPLATE/02_bug.yaml | 2 +- docs/development/index.md | 3 +- docs/development/posting-issues.md | 70 +++++++++++++++++++++++++++ 4 files changed, 75 insertions(+), 2 deletions(-) create mode 100644 docs/development/posting-issues.md diff --git a/.github/ISSUE_TEMPLATE/01_feature.yml b/.github/ISSUE_TEMPLATE/01_feature.yml index 7b7b6449e2..1a7a105425 100644 --- a/.github/ISSUE_TEMPLATE/01_feature.yml +++ b/.github/ISSUE_TEMPLATE/01_feature.yml @@ -21,6 +21,8 @@ body: Provide a clear and concise description of what the problem is. For example: - "I'm trying to simulate particle behavior with [specific physics], but Parcels doesn't support..." - "When working with [specific data format/kernel], I find it difficult to..." + + If you would like to see Parcels work with a specific dataset, please also [follow our instructions on how to share dataset metadata](https://docs.oceanparcels.org/en/v4-dev/development/posting-issues.html). validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/02_bug.yaml b/.github/ISSUE_TEMPLATE/02_bug.yaml index 98966df6de..1d7bd41611 100644 --- a/.github/ISSUE_TEMPLATE/02_bug.yaml +++ b/.github/ISSUE_TEMPLATE/02_bug.yaml @@ -17,7 +17,7 @@ body: - type: "textarea" attributes: label: "Code sample" - description: "If relevant, please provide a code example where this bug is shown as well as any error message. A [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) is preffered as it makes it much easier for developers to identify the cause of the bug. This also allows them quickly determine whether the problem is with your code or with Parcels itself." + description: "If relevant, please provide a code example where this bug is shown as well as any error message. A [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) is preffered as it makes it much easier for developers to identify the cause of the bug. This also allows them quickly determine whether the problem is with your code or with Parcels itself. If you want support on a specific dataset, please [follow our instructions on how to share dataset metadata](https://docs.oceanparcels.org/en/v4-dev/development/posting-issues.html)" value: | ```python # Paste your code within this block diff --git a/docs/development/index.md b/docs/development/index.md index 56edf70fcd..aaffd27fd1 100644 --- a/docs/development/index.md +++ b/docs/development/index.md @@ -17,6 +17,7 @@ Release Notes maintainer docsguide +posting-issues ``` ## Why contribute? @@ -55,7 +56,7 @@ Exactly how to use Git and GitHub is beyond the scope of this documentation, and There are many ways that you can contribute to Parcels. You can: -- Participate in discussion about Parcels, either through the [issues](https://github.com/Parcels-code/parcels/issues) or [discussions](https://github.com/Parcels-code/parcels/discussions) tab +- Participate in discussion about Parcels, either through the [issues](https://github.com/Parcels-code/parcels/issues) or [discussions](https://github.com/Parcels-code/parcels/discussions) tab. See our guide on [posting-issues](./posting-issues.md). - Suggest improvements to [tutorials and how-to guides](../user_guide/index.md) - Suggest improvements to [documentation](../index.md) - Write code (fix bugs, implement features, codebase improvements, etc) diff --git a/docs/development/posting-issues.md b/docs/development/posting-issues.md new file mode 100644 index 0000000000..88347085f8 --- /dev/null +++ b/docs/development/posting-issues.md @@ -0,0 +1,70 @@ +--- +file_format: mystnb +kernelspec: + name: python3 +--- + +# Participating in the issue tracker + +We love hearing from our community! +We want to be able to support you in your workflows, and learn about how you use Parcels. +In open source projects, getting feedback from users is hard - you posting +issues and participating in the issue tracker is really useful for us and +helps future development and squash bugs. + +Parcels provides issue templates for when posting issues. +Following these templates provides structure and ensures that we have all the necessary information we need to help you. + +## "Parcels doesn't work with my input dataset" + +Parcels is designed to work with a large range of input datasets. + +When extending support for various input datasets, or trying to debug problems +that only occur with specific datasets, having the dataset metadata is very valuable. + +This metadata could include information such as: + +- CF compliant metadata +- descriptions about the origin of the dataset, or additional comments +- the shapes and data types of the arrays + +This also allows us to see if your metadata is broken/non-compliant with standards - where we can then suggest fixes for you (and maybe we can tell the data provider!). +Since version 4 of Parcels we rely much more on metadata to discover information about your input data. + +Sharing this metadata often provides enough debugging information to solve your problem, instead of having to share a whole dataset. + +Sharing dataset metadata is made easy in Parcels. + +### Step 1. Users + +As a user with access to your dataset, you would do: + +```{code-cell} +import json + +import xarray as xr + +# defining an example dataset to illustrate +# (you would use `xr.open_dataset(...)` instead) +ds = xr.Dataset(attrs={"description": "my dataset"}) + +output_file = "my_dataset.json" +with open(output_file, "w") as f: + json.dump(ds.to_dict(data=False), f) # write your dataset to a JSON excluding array data +``` + +Then attach the produced JSON file alongside your issue + +### Step 2. Maintainers and developers + +As developers looking to inspect the metadata, we would do: + +```{code-cell} +from parcels._datasets.utils import from_xarray_dataset_dict + +with open(output_file) as f: + d = json.load(f) +ds = from_xarray_dataset_dict(d) +``` + +From there we can take a look the metadata of your dataset! From 95904870e5263796730b9d4d6a4d17ef44af056c Mon Sep 17 00:00:00 2001 From: Nick Hodgskin <36369090+VeckoTheGecko@users.noreply.github.com> Date: Fri, 13 Feb 2026 10:46:18 +0100 Subject: [PATCH 3/7] Update docs/development/posting-issues.md Co-authored-by: Erik van Sebille --- docs/development/posting-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/posting-issues.md b/docs/development/posting-issues.md index 88347085f8..30060749a5 100644 --- a/docs/development/posting-issues.md +++ b/docs/development/posting-issues.md @@ -53,7 +53,7 @@ with open(output_file, "w") as f: json.dump(ds.to_dict(data=False), f) # write your dataset to a JSON excluding array data ``` -Then attach the produced JSON file alongside your issue +Then attach the JSON file written above alongside your issue ### Step 2. Maintainers and developers From 41745e74e5f0209d5e71d8e7ad58e43beabf407a Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Fri, 13 Feb 2026 10:47:53 +0100 Subject: [PATCH 4/7] Update maintainer notes We no longer use Lychee --- docs/development/maintainer.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/development/maintainer.md b/docs/development/maintainer.md index d8d5dd4fad..d284493a5b 100644 --- a/docs/development/maintainer.md +++ b/docs/development/maintainer.md @@ -27,6 +27,5 @@ - Update parcels-code.org - Parcels development status - Check feature tiles - - Check for broken links on oceanparcels using [this tracking issue](https://github.com/Parcels-code/parcels-code.org/issues/85) - (once package is available on conda) Re-build the Binder - Ask for the shared parcels environment on [Lorenz](https://github.com/IMAU-oceans/Lorenz) to be updated From 49e8ae957f5cb6374b20130dce104928fe0453ee Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Fri, 13 Feb 2026 10:51:46 +0100 Subject: [PATCH 5/7] Update URLs in issue templates --- .github/ISSUE_TEMPLATE/01_feature.yml | 2 +- .github/ISSUE_TEMPLATE/02_bug.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/01_feature.yml b/.github/ISSUE_TEMPLATE/01_feature.yml index 1a7a105425..634e1359b0 100644 --- a/.github/ISSUE_TEMPLATE/01_feature.yml +++ b/.github/ISSUE_TEMPLATE/01_feature.yml @@ -22,7 +22,7 @@ body: - "I'm trying to simulate particle behavior with [specific physics], but Parcels doesn't support..." - "When working with [specific data format/kernel], I find it difficult to..." - If you would like to see Parcels work with a specific dataset, please also [follow our instructions on how to share dataset metadata](https://docs.oceanparcels.org/en/v4-dev/development/posting-issues.html). + If you would like to see Parcels work with a specific dataset, please also [follow our instructions on how to share dataset metadata](https://docs.parcels-code.org/en/v4-dev/development/posting-issues.html). validations: required: true - type: textarea diff --git a/.github/ISSUE_TEMPLATE/02_bug.yaml b/.github/ISSUE_TEMPLATE/02_bug.yaml index 1d7bd41611..4fc9f4d93c 100644 --- a/.github/ISSUE_TEMPLATE/02_bug.yaml +++ b/.github/ISSUE_TEMPLATE/02_bug.yaml @@ -17,7 +17,7 @@ body: - type: "textarea" attributes: label: "Code sample" - description: "If relevant, please provide a code example where this bug is shown as well as any error message. A [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) is preffered as it makes it much easier for developers to identify the cause of the bug. This also allows them quickly determine whether the problem is with your code or with Parcels itself. If you want support on a specific dataset, please [follow our instructions on how to share dataset metadata](https://docs.oceanparcels.org/en/v4-dev/development/posting-issues.html)" + description: "If relevant, please provide a code example where this bug is shown as well as any error message. A [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) is preffered as it makes it much easier for developers to identify the cause of the bug. This also allows them quickly determine whether the problem is with your code or with Parcels itself. If you want support on a specific dataset, please [follow our instructions on how to share dataset metadata](https://docs.parcels-code.org/en/v4-dev/development/posting-issues.html)" value: | ```python # Paste your code within this block From 280c24246126c10d0cf9605355c60d5fdd448361 Mon Sep 17 00:00:00 2001 From: Nick Hodgskin <36369090+VeckoTheGecko@users.noreply.github.com> Date: Fri, 13 Feb 2026 10:52:18 +0100 Subject: [PATCH 6/7] Update docs/development/posting-issues.md Co-authored-by: Erik van Sebille --- docs/development/posting-issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/posting-issues.md b/docs/development/posting-issues.md index 30060749a5..cb75b3bcbe 100644 --- a/docs/development/posting-issues.md +++ b/docs/development/posting-issues.md @@ -12,7 +12,7 @@ In open source projects, getting feedback from users is hard - you posting issues and participating in the issue tracker is really useful for us and helps future development and squash bugs. -Parcels provides issue templates for when posting issues. +Parcels provides issue templates that you can use when posting issues. Following these templates provides structure and ensures that we have all the necessary information we need to help you. ## "Parcels doesn't work with my input dataset" From 036f4df4fabd0489c451d79e08efc0fa5d198b6c Mon Sep 17 00:00:00 2001 From: Vecko <36369090+VeckoTheGecko@users.noreply.github.com> Date: Fri, 13 Feb 2026 11:03:56 +0100 Subject: [PATCH 7/7] Review feedback --- docs/development/posting-issues.md | 2 +- docs/getting_started/tutorial_output.ipynb | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/posting-issues.md b/docs/development/posting-issues.md index cb75b3bcbe..6edd911d37 100644 --- a/docs/development/posting-issues.md +++ b/docs/development/posting-issues.md @@ -24,7 +24,7 @@ that only occur with specific datasets, having the dataset metadata is very valu This metadata could include information such as: -- CF compliant metadata +- the nature of the array variables (e.g., via CF compliant metadata) - descriptions about the origin of the dataset, or additional comments - the shapes and data types of the arrays diff --git a/docs/getting_started/tutorial_output.ipynb b/docs/getting_started/tutorial_output.ipynb index 0b7def37c1..cd8dcbc1a0 100644 --- a/docs/getting_started/tutorial_output.ipynb +++ b/docs/getting_started/tutorial_output.ipynb @@ -560,7 +560,7 @@ "metadata": { "celltoolbar": "Metagegevens bewerken", "kernelspec": { - "display_name": "docs", + "display_name": "test-notebooks", "language": "python", "name": "python3" },