zabbix-patch

name	zabbix-patch
description	Use this skill when generating, updating, or reviewing a Zabbix source patch in zabbix/patches/. Handles the critical schema patching gotcha — schema changes must touch BOTH create/src/schema.tmpl AND ui/include/schema.inc.php, or DB::insert/DB::update will silently drop columns at runtime.

Zabbix source patches

The full workflow lives in development/patching.md. This skill is the operator-level checklist plus the schema gotcha not yet documented there.

When to use

• Adding a new patch to zabbix/patches/
• Updating an existing patch for a new Zabbix version
• Reviewing whether an existing patch is complete (especially schema patches)

The schema gotcha

Schema changes must touch two files, not one. Patching only schema.tmpl looks correct, builds successfully, and creates the column in the database — but DB::insert and DB::update calls will silently drop the column at runtime.

File	Used by	Purpose
create/src/schema.tmpl	Bootstrap	Compiles into create.sql.gz and dbschema.c. Defines the table at first install.
ui/include/schema.inc.php	Runtime	PHP metadata consulted by DB::insert / DB::update. Unknown columns are silently dropped.

The published development/patching.md currently states that schema.inc.php is auto-generated from schema.tmpl. This is incorrect. Both files are committed in the Zabbix source and both must be modified by hand. The existing 0001-sla-min-severity.patch is the reference example — it touches both files.

When generating a schema-touching patch, always grep your patch file for both paths before considering it done:

grep -E "schema\.(tmpl|inc\.php)" zabbix/patches/<your-patch>.patch

If you only see one of them, the patch is incomplete.

Naming conventions

• All Omniglass columns added to Zabbix tables use the og_ prefix to avoid namespace collisions when Zabbix ships features upstream
• Patch filenames: NNNN-feature-name.patch where the numeric prefix controls apply order alphabetically
• 0000- is reserved for security/dependency CVE fixes (always first)
• Feature patches start at 0001- and go up

Procedure summary

The full procedure is in development/patching.md. The quick version, with paths expressed as shell variables so the skill works in any environment:

# Set these once at the top of your session
OMNIGLASS=/path/to/omniglass               # this repo
ZBX_FORK=/path/to/hyperscaleav-zabbix      # local checkout of hyperscaleav/zabbix

# ZABBIX_VERSION contains a comment line followed by the version. Parse it the
# same way scripts/build-zabbix.sh and tests/e2e/scripts/setup-stack.sh do:
ZBX_TAG=$(grep -vE '^\s*(#|$)' "$OMNIGLASS/ZABBIX_VERSION" | head -n1)

1. Branch from the Zabbix version tag in the hyperscaleav/zabbix fork:

   cd "$ZBX_FORK"
   git fetch origin --tags
   git checkout "$ZBX_TAG"
   git checkout -b omniglass/<feature>
   

2. Make changes. For schema changes, edit BOTH create/src/schema.tmpl AND ui/include/schema.inc.php. Use the og_ prefix on any new columns added to Zabbix tables.

3. Generate the patch against the same version tag:

   git diff "$ZBX_TAG" > "$OMNIGLASS/zabbix/patches/NNNN-<feature>.patch"
   

4. Verify the patch is complete before building:

   grep -E "schema\.(tmpl|inc\.php)" "$OMNIGLASS/zabbix/patches/NNNN-<feature>.patch"
   # If schema is touched, BOTH files must appear
   

5. Rebuild and test from the omniglass repo:

   cd "$OMNIGLASS"
   rm -rf /tmp/zabbix-docker-*   # clear cache when patches change
   make build
   make test-e2e
   

6. Push and tag in the fork:

   cd "$ZBX_FORK"
   git push omniglass omniglass/<feature>
   git tag "omniglass/$ZBX_TAG/<feature>"
   git push omniglass "omniglass/$ZBX_TAG/<feature>"
   

Source reference

Always verify against the actual Zabbix source in your local fork ($ZBX_FORK above) before generating a patch. Do not guess at file paths or function names.