project-netdata-vendoring

name	project-netdata-vendoring
description	Mandatory workflow for copying, syncing, vendoring, or merging plugin-ipc NetIPC source changes into a Netdata checkout. Use whenever work mentions Netdata vendoring, vendor drift, vendor-to-netdata, diff-netdata-vendor.sh, vendor-to-netdata.sh, or updating src/libnetdata/netipc, src/crates/netipc, or src/go/pkg/netipc in Netdata.

Netdata Vendoring Preflight

Purpose

Netdata consumes NetIPC from this repository as vendored source. Before touching a Netdata checkout, prove that the source plugin-ipc commit is safe enough to copy downstream.

Mandatory Rule

Do this preflight before any Netdata vendoring work, even if the user only asks to copy, sync, vendor, merge, push, or continue.

Do not modify the Netdata vendored copy until:

• the candidate plugin-ipc commit is identified;
• source CI and GitHub code/security scanner status are checked;
• the last vendored baseline is identified or explicitly reconstructed;
• two-way drift is understood:
  • what changed in plugin-ipc since the last vendoring;
  • what changed in Netdata's vendored NetIPC copy since the last vendoring;
• a migration plan exists for every drift class;
• failures and open alerts are fixed, documented as evidence-backed false positives, or explicitly risk-accepted by the user in the active SOW.

Scope Trigger

Load this skill for any task involving:

• ~/src/netdata-ktsaou.git or another Netdata checkout receiving NetIPC files;
• vendor-to-netdata.sh;
• diff-netdata-vendor.sh;
• Netdata paths such as:
  • src/libnetdata/netipc/
  • src/crates/netipc/
  • src/go/pkg/netipc/
• statements like "vendor", "vendored", "copy to Netdata", "sync to Netdata", "merge to Netdata", or "update Netdata's NetIPC copy".

Preflight Steps

1. Resolve the source commit.

   git rev-parse HEAD
   git status --short --branch
   git remote -v
   

   The source commit must be pushed or otherwise available to GitHub checks. If local uncommitted source changes are intended for vendoring, stop and make the source repository state explicit before touching Netdata.

2. Check GitHub Actions and commit checks for the source commit.

   gh run list --repo netdata/plugin-ipc --commit "$COMMIT" \
     --limit 50 \
     --json databaseId,name,status,conclusion,createdAt,updatedAt,url,headBranch,headSha
   
   gh api "repos/netdata/plugin-ipc/commits/$COMMIT/check-runs" \
     --jq '.check_runs[] | {name, status, conclusion, html_url}'
   
   gh api "repos/netdata/plugin-ipc/commits/$COMMIT/status" \
     --jq '{state, total_count, statuses}'
   

   Required result: no failing, cancelled, timed-out, or pending required checks unless the active SOW records why the result does not apply.

3. Check GitHub code/security scanners.

   gh api 'repos/netdata/plugin-ipc/code-scanning/alerts?state=open&per_page=100' \
     --jq '[.[] | {number, tool: .tool.name, rule: .rule.id, severity: .rule.severity, path: .most_recent_instance.location.path, line: .most_recent_instance.location.start_line, message: .most_recent_instance.message.text, url: .html_url}]'
   
   gh api 'repos/netdata/plugin-ipc/dependabot/alerts?state=open&per_page=100' \
     --jq '[.[] | {number, package: .dependency.package.name, ecosystem: .dependency.package.ecosystem, severity: .security_advisory.severity, manifest: .dependency.manifest_path, url: .html_url}]'
   
   gh api 'repos/netdata/plugin-ipc/secret-scanning/alerts?state=open&per_page=100' \
     --jq '[.[] | {number, secret_type, state, resolution, url: .html_url}]'
   

   Required result: no untriaged open code-scanning, dependency, or secret alerts for the candidate source branch/commit. If alerts exist, record exact files/rules and stop unless they are fixed, evidence-backed false positives, or explicitly accepted by the user.

4. Establish the last vendored baseline.

   Find the last Netdata commit or PR that updated the vendored NetIPC trees:

Blockers

Stop and report if any of these are true:

• source commit has no GitHub CI/check-run evidence;
• source CI is failing, pending, cancelled, or timed out;
• GitHub code scanning has untriaged open alerts;
• Dependabot has untriaged open alerts;
• secret scanning has open alerts;
• the last source-to-Netdata vendoring baseline cannot be identified or reconstructed with evidence;
• either side has NetIPC changes since the last vendoring that are not understood;
• the active SOW does not contain a migration plan for both directions;
• source tree has uncommitted changes that are intended for vendoring;
• Netdata checkout has unrelated changes that would be hard to isolate.

Reporting Shape

Use this concise report before vendoring:

Netdata vendoring preflight:
- Source commit: <sha>
- Baseline: plugin-ipc <sha>, Netdata <sha>
- CI/checks: <pass/fail/pending summary>
- Code scanning: <count by tool/severity, exact blockers>
- Dependabot: <open count>
- Secret scanning: <open count>
- Upstream gap: <summary of plugin-ipc changes since baseline>
- Downstream gap: <summary of Netdata vendored changes since baseline>
- Migration plan: <preserve/backport/overwrite/decision summary>
- Decision: proceed | blocked | proceed with user-accepted risk