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/2] 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/2] 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!