DOCS: Add guide on sharing dataset metadata (#2510)

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

Author: VeckoTheGecko

.github/ISSUE_TEMPLATE/01_feature.md

@@ -0,0 +1,61 @@
+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..."
+
+        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
+    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

.github/ISSUE_TEMPLATE/01_feature.yml

@@ -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.parcels-code.org/en/v4-dev/development/posting-issues.html)"
       value: |
         ```python
         # Paste your code within this block

.github/ISSUE_TEMPLATE/02_bug.yaml

@@ -17,6 +17,7 @@ Release Notes <https://github.com/Parcels-code/Parcels/releases>
 
 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)

docs/development/index.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

docs/development/maintainer.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 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"
+
+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:
+
+- 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
+
+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 JSON file written above 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!

docs/development/posting-issues.md

@@ -560,7 +560,7 @@
  "metadata": {
   "celltoolbar": "Metagegevens bewerken",
   "kernelspec": {
-   "display_name": "docs",
+   "display_name": "test-notebooks",
    "language": "python",
    "name": "python3"
   },