# Recipe: update an existing collector integration

Use this when a collector's metrics, chart contexts, configuration,
alerts, or generated docs change. The goal is to keep runtime behavior,
metadata, taxonomy, source documentation, and CI validation coherent. Generated
integration pages may ship in the source PR or through the automatic post-merge
regeneration PR.

## 0. Read first

- `../SKILL.md` -- integrations lifecycle overview.
- `../consistency.md` -- what the collector consistency rule requires
  and what CI enforces.
- `../schema-reference.md` -- exact `metadata.yaml` and
  `taxonomy.yaml` fields.

## 1. Identify what changed

From the collector directory, list the changed surfaces:

- runtime `.go` / script code;
- `metadata.yaml` metric contexts, units, dimensions, setup, alerts;
- `taxonomy.yaml` dashboard TOC placement;
- `config_schema.json`;
- stock `.conf`;
- `health.d/*.conf`;
- generated `integrations/<slug>.md` and `README.md` symlink.

If chart contexts are added, removed, renamed, or moved between dynamic
and static emission, update `taxonomy.yaml` in the same PR.

## 2. Update `metadata.yaml`

Keep `metrics.scopes[].metrics[].name` aligned with the collector's
actual emitted chart contexts. Keep units and descriptions aligned with
the code. If a collector emits runtime-only dynamic contexts, declare
the guardrail in metadata:

```yaml
metrics:
  dynamic_context_prefixes:
    - prefix: snmp.
      reason: SNMP profiles emit device-specific contexts at runtime.
```

Use `dynamic_collect_plugins` only when a stable context-name prefix is
not available.

## 3. Update `taxonomy.yaml`

Check whether the existing taxonomy still owns every static context
exactly once:

```bash
python3 integrations/gen_taxonomy.py --check-only
```

Rules of thumb:

- plain strings in structural `items:` own contexts;
- `type: context` widgets reference contexts but do not own them;
- every literal widget reference must be owned elsewhere or carry an
  explicit `unresolved` escape hatch;
- dynamic collectors use `type: selector` with declared
  `context_prefix:` or `collect_plugin:`;
- pick section IDs from `integrations/taxonomy/sections.yaml`.

For a modern go.d V2 ownership reference, compare against
`src/go/plugin/go.d/collector/cato_networks/taxonomy.yaml`. If the change needs
grid or table widget examples, compare against
`src/go/plugin/go.d/collector/mysql/taxonomy.yaml`.

## 4. Update the remaining collector artifacts

Keep these synchronized when the corresponding behavior changes:

- `config_schema.json` for dynamic configuration;
- stock `.conf` for user-visible defaults;
- `health.d/*.conf` and `metadata.yaml.modules[].alerts[]`;
- generated docs through the explicitly selected same-PR or post-merge route.

Do not hand-edit generated `integrations/<slug>.md` files.

## 5. Run local validation

From the repo root:

```bash
python3 integrations/gen_integrations.py
python3 integrations/gen_taxonomy.py --check-only
python3 integrations/check_collector_taxonomy.py --pr-diff master...HEAD
python3 -m unittest integrations.tests.test_taxonomy
# When committing generated docs in this PR:
python3 integrations/gen_docs_integrations.py -c go.d.plugin/<module>
python3 integrations/gen_doc_collector_page.py
python3 integrations/gen_doc_secrets_page.py
# If service-discovery rules or sdext metadata changed:
python3 integrations/gen_doc_service_discovery_page.py
```

Skip the three generated-doc commands when the source PR explicitly selects the
automatic post-merge regeneration route. `check-markdown.yml` and
`generate-integrations.yml` run them in CI.

Use the repo-local `.venv/bin/python` when one exists for the current
worktree. If your local base branch is not `master`, adjust the `--pr-diff`
range to the PR base.

If service-discovery rules or `sdext` metadata changed, run
`python3 integrations/gen_doc_service_discovery_page.py` and commit
`src/collectors/SERVICE-DISCOVERY.md`; this is not handled by CI for you.

## 6. Before opening the PR

Run:

```bash
git status --short
git status --porcelain |
  rg '^(\?\?|!!| M|M |A |AM) integrations/(integrations\.(js|json)|taxonomy\.json)$' || true
```

Commit source and taxonomy changes together. Either commit regenerated docs in
the same PR or state that `generate-integrations.yml` will open the post-merge
regeneration PR; do not leave the delivery route implicit.
Do not commit gitignored runtime artifacts such as
`integrations/integrations.js`, `integrations/integrations.json`, or
`integrations/taxonomy.json`.

The generated-artifact status grep MUST return no output before the PR is
opened. If it reports one of those files, remove the local generated artifact
from the commit/worktree state rather than committing it.
