doca-upgrade

Files (7)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# DOCA upgrade

## Examples

- **"Should I move to the next DOCA release?"** — detect what is
  installed, report the gap, then STOP and ask. Never auto-upgrade.
- **"apt upgrade drifted my DOCA packages."** — this is recovery,
  not a silent repair. Detect, report, ask, then guide.

## Quick answers (answer from this file)

- **Not changing versions** (a runtime error on the current, pinned
  install)? This skill does not apply: name `doca-debug` and stop.

These two answers are complete here; open `TASKS.md` only for a guided
upgrade after the user confirms. Run only the read-only detection
commands yourself. Package commands (`sudo dpkg`, `apt`, `apt-get`) need
root and change the system: give them to the user to run and stop; in an
agent shell `sudo` waits for a password and the session stalls.

- **"Can I just `apt upgrade` to the next DOCA?"** Never upgrade
  automatically. Detect the installed release with the `doca-version`
  four-source chain (`pkg-config --modversion doca-common`,
  `cat /opt/mellanox/doca/applications/VERSION`, `doca_caps --version`, and
  the BFB version on BlueField), report the gap to the target release, then
  STOP and ask for explicit confirmation. BFB, firmware or reboot steps follow
  `doca-hardware-safety`.
- **"The upgrade aborted half-way and dpkg reports an interrupted
  transaction."** Recover the package database first:
  after the user explicitly confirms (both commands change system package
  state), the user runs `sudo dpkg --configure -a`, then
  `sudo apt-get -f install` (Debian/Ubuntu). Do not re-run the upgrade as the first action; re-detect
  the release with `doca-version` before deciding the next step.

## Instructions

Follow Loading order below. Open the tasks companion for detect →
report → ASK → guided upgrade. Open the capabilities companion for
the upgrade-mode taxonomy and refuse-auto-upgrade rule. Do not open
every companion file.

**Where to start:** This skill is the bundle's single source of
truth for the discipline that wraps a DOCA *upgrade or downgrade*.
Open the tasks companion when the user wants to *do* something
with an upgrade (detect the gap, ask for confirmation, walk the
guided upgrade, verify it, or diagnose a failed one); open
the capabilities companion when the question is *what does
an upgrade even cover* (the host apt-upgrade vs BFB reflash vs
container-tag bump vs downgrade/rollback modes, the never-auto rule,
the confirmation gate, the sunset-awareness concern, the error
taxonomy, and the upgrade-specific safety overlay).

**How to use this skill.** Read this file, then search the companion file
for the `## <name>` heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in `doca-public-knowledge-map`. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.

**For a planned move, the single most important rule this skill
exists to enforce is detect → report → ASK → only-then guided
upgrade. Never upgrade automatically.** The skill detects the
installed DOCA env and what newer release is available, reports the
gap clearly, then STOPS and asks the user for explicit confirmation.
Only on an explicit "yes" does it walk a guided upgrade. A failed or
partial move instead enters the recovery ladder without presenting a
new target move. In both paths every hardware / firmware / reboot
step is delegated to
`doca-hardware-safety/SKILL.md`, never
redefined here. Version detection itself is owned by
`doca-version/SKILL.md`; this skill routes there
and does not restate the detection chain.

## Example questions this skill answers well

The CLASSES of upgrade 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.

- **"Is there a newer DOCA than what I have, and how far behind am
  I?"** — worked example: *"`pkg-config --modversion doca-common`
  says `<installed X.Y.Z>`; what's current and what does moving cost me?"*.
  Answered by the detect-and-report-the-gap workflow in
  ## configure, which routes the
  detection to `doca-version/SKILL.md` and the
  *what is current* lookup to
  `doca-public-knowledge-map/SKILL.md`.
- **"Should I just run `apt upgrade` to move to the next DOCA
  release?"** — worked example: *"I want the newest Flow features;
  can I upgrade in place right now?"*. Answered by the never-auto
  rule and the confirmation gate in
  ## Safety policy
  plus the ask-before-acting step in
  ## run — the agent reports the gap and
  STOPS for explicit confirmation before any upgrade command runs.
- **"My upgrade left the host on a different release than the
  BlueField — what happened?"** — worked example: *"after the
  upgrade `pkg-config` reports the new release but `bfver` still reports the old one"*.
  Answered by the host/BFB-skew row in
  ## Error taxonomy
  and the failed-upgrade diagnosis in
  ## debug, which re-routes the
  detection to `doca-version ## test`.
- **"The upgrade aborted half-way and now `dpkg` is wedged — how do
  I recover?"** — worked example: *"`apt upgrade` was interrupted;
  `dpkg` reports an interrupted transaction"*. Answered by the
  partial-upgrade and aborted-transaction rows in
  ## Error taxonomy
  plus the recovery ladder in ## debug.
- **"The upgrade needs me to reflash the BFB / flip BlueField mode /
  reboot — is that safe?"** — worked example: *"the target release
  requires a new BFB; can I reflash now?"*. Answered by routing
  every hardware / firmware / reboot step to
  `doca-hardware-safety/SKILL.md` via
  ## run; this skill never redefines the
  reflash, mode-flip, or cold-power-cycle discipline.
- **"My installed component is being sunset — should I keep building
  on it or move?"** — worked example: *"I rely on DOCA App Shield /
  the DOCA Flow Inspector service; are they on a

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills