Add troubleshooting section (#2565)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: jaimergp <[email protected]>

Author: 3 people

docs/maintainer/updating_pkgs.md

@@ -346,3 +346,53 @@ If you'd like to maintain more than one version of your package, you can use bra
 - Fork your feedstock and make a meaningful branch name (e.g., v1.X or v1.0).
 - Make the required changes to the recipe and rerender the feedstock.
 - Then push this branch from your fork to the upstream feedstock. Our CI services will automatically build any branches in addition to the default branch.
+
+## Troubleshooting
+
+Sometimes things go wrong, particularly with the automation. This section aims to provide guidance on these problems.
+
+### Automatic version updates don't work
+
+Usually, the bot detects automatically when a new version of a package is released.
+It does that by monitoring the source url named in the recipe in an appropriate way,
+i.e. for PyPI sources it queries the API, for Github source releases it monitors the release page
+or the tags in the upstream repository.
+Sometimes an erroneous release happens or an unrelated tag is misidentified as a release.
+For example, `project-a` usually releases under a semver scheme like 4.0.2, but a typo in the release process ended up creating a tag with 40.3 (missing period).
+In these cases, the bot can be confused, consider subsequent releases as older than the misidentified one, and stop issuing automatic update PRs.
+
+You can check which version the bot detected by looking in the metadata that it collected, which is conveniently available in its own Github repo.
+To deal with the large number of packages, the information is sharded (i.e. split into several subdirectories) according to some hash function,
+which makes it a bit challenging to find.
+The best way is to use Github search with the query [`repo:regro/cf-graph-countyfair path:version_pr_info/**/amrex.json`](https://github.com/search?q=repo%3Aregro%2Fcf-graph-countyfair+path%3Aversion_pr_info%2F**%2Famrex.json&type=code), where you should replace `amrex` with the name of your own package.
+This will lead you to a file looking like:
+
+```json
+{
+  "bad": false,
+  "new_version": "25.07",
+  "new_version_attempts": {
+    "2024": 0,
+    "23.11": 1,
+    "23.12": 1,
+    "24.01": 1,
+    "24.02": 1,
+    "24.03": 1
+  },
+  "new_version_errors": {}
+}
+```
+
+Here, look for the `"new_version"` field. If that contains a wrong value, note it down for fixing in the next step.
+
+The solution in this case is to let the bot know that it should ignore a certain version.
+This can be done in the `conda-forge.yml` configuration file, with [more details](../conda_forge_yml/#bot) in the documentation, the simple snippet boils down to
+
+```yaml
+bot:
+  version_updates:
+    exclude:
+      - '08.14'
+```
+
+where `'08.14'` represents the erroneous version.