/doca-version

license: Apache-2.0
name: doca-version
description: >
  DOCA version handling: detect the installed release and validate the
  four-way match across pkg-config doca-common, applications/VERSION,
  doca_caps --version, and bfver/mlnx-release on BlueField; reason about
  NGC tags; look up whether a capability exists on this release; diagnose
  build-vs-runtime drift. Use this skill alongside doca-debug when a symptom
  smells of version skew: "built but nothing on the wire", "undefined
  reference to a symbol the docs claim exists", "DOCA_ERROR_NOT_SUPPORTED
  at runtime", "what does latest mean for this tag", or "is my LTS still
  supported". Once all four sources match, the component's build / run
  workflow belongs to its own library, service or tool skill. Refuse
  install / package choice (doca-setup), per-library API questions
  (matching library skill), DOCA_ERROR_* taxonomy
  (doca-programming-guide), and the general debug ladder (doca-debug).
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - version
    - compatibility
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca.

DOCA version

Examples

• **"What DOCA version do I actually have installed?"** — run the

four-source detection chain and require a four-way match.

• **"The program built but does nothing on the wire."** — treat

mixed-install drift as a version problem before rewriting application code.

Instructions

Follow Loading order below. Open the tasks companion for detect / validate / diagnose, and the capabilities companion for the four-way match and NGC tag rules. Do not open every companion file.

**Where to start:** This skill is the bundle's single source of truth for DOCA *version handling*. Open the tasks companion if the user wants to *do* something with the version (detect / validate / diagnose mismatch); open the capabilities companion when the question is *what does version handling cover* (the four-way match, the detection chain, NGC semantics, the per-library overlay pattern). Every other skill in the bundle that touches version routes here — they MUST NOT redefine the rules.

Example questions this skill answers well

The CLASSES of version-handling questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"What DOCA version do I actually have installed?"** — worked

example: *"the docs say 3.3 but I'm not sure what's on this host"*. Answered by the canonical detection chain in

configure +

Capabilities and modes

source-of-truth table.

• **"My program built but does nothing on the wire — is my install

consistent?"** — worked example: *"`pkg-config --modversion` says 3.3.0; `doca_caps --version` says 3.2.0"*. Answered by the four-way match rule in

Version compatibility

• the partial-install diagnosis in

debug.

• **"Is this DOCA capability / API / sample on the version I

have?"** — worked example: *"is the symmetric-RSS hash mode in Flow 2.6.0"*. Answered by the version-matrix lookup procedure in

test (which uses the

`version-matrix.json` schema defined in `doca-structured-tools-contract/SKILL.md#schemas` with fallback to per-library docs via `doca-public-knowledge-map/SKILL.md`).

• **"Can I run my host package version X against BFB version Y?"** —

worked example: *"host is 3.5.0 GA, BlueField BFB is 3.2.3 LTS"*. Answered by the routing to the [DOCA Compatibility Policy](https://docs.nvidia.com/doca/sdk/doca-compatibility-policy/index.html) documented in

Version compatibility.

• **"I'm inside the NGC DOCA container — what does the version

match look like?"** — worked example: *"do I still need to check pkg-config / applications/VERSION / doca_caps separately?"*. Answered by the NGC container rule in

Version compatibility

• the container path in

configure.

• **"How do I write a per-library version-compatibility section

for a new skill?"** — worked example: *"adding `doca-comch` to the bundle, what does its `## Version compatibility` look like?"*. Answered by the per-library overlay pattern in

Safety policy

• the worked-example template in

modify.

• **"My `apt list` shows DOCA `3.3.0109`, but `/etc/apt/sources.list.d/doca.list`

is pinned at `latest` / a different release — is the next `apt install doca-*` going to silently upgrade me?"** — worked example: *"I rolled back BFB to 3.1.0105 but my sources still point at the latest channel."* Answered by the apt-source consistency precheck in

apt-source consistency,

which enumerates the three legitimate shapes of a configured DOCA apt source (network URL, local file-repo, RHEL/OEL equivalent) and the *do-not-install-until-the-source-matches* rule that protects pinned installs from accidental drift.

When to load this skill

Load this skill whenever version handling is the load-bearing concern. The decision must be made **before** the agent composes its first sentence — the activation checklist below is the same one referenced from `AGENTS.md ## Cross-cutting overlay activation triggers` (bundle `AGENTS.md#cross-cutting-overlay-activation-triggers`), mirrored here so the activation rule is at hand whenever this skill is consulted.

Agent activation checklist — load this skill at the START of the answer when any cell below is true

| Trigger class | Concrete prompt-side signals (any one fires the overlay) | | --- | --- | | Direct version question | *"what DOCA version do I have"*, *"is X consistent"*, *"is feature Y supported on version Z"*, *"can I mix host package version A with BFB version B"*, *"is my LTS still supported"*, *"what does the version string mean"* | | Container ta