info: clarify APICapability and OptionalCapabilities docs - #153
Open
eriknordmark wants to merge 2 commits into
Open
info: clarify APICapability and OptionalCapabilities docs#153eriknordmark wants to merge 2 commits into
eriknordmark wants to merge 2 commits into
Conversation
eriknordmark
requested review from
milan-zededa,
rene and
uncleDecart
and removed request for
uncleDecart
August 7, 2026 20:51
eriknordmark
force-pushed
the
document-api-capabilities
branch
from
August 7, 2026 21:42
4f54631 to
2411b71
Compare
eriknordmark
marked this pull request as draft
August 7, 2026 21:42
APICapability covers two kinds of support: EdgeDevConfig fields EVE-OS parses, and messages EVE-OS sends. The latter is not evident from the existing comment, yet it matters just as much - without API_CAPABILITY_SMART_REPORT a controller would wait indefinitely for S.M.A.R.T. information in ZHardwareHealth. Record that, and state explicitly that the enum is a monotonic level to be compared with >= rather than a set of flags. OptionalCapabilities is the opposite: independent booleans varying by build flavor. Add CAPABILITIES.md with a table of what each value covers and a checklist for controller implementers; five rows are marked as inferred rather than authoritative and want review. Also give hw_inventory_support its first comment, distinguish the hardware-oriented Capabilities message from the other two, and fix a truncated, a duplicated and an ungrammatical comment. Signed-off-by: eriknordmark <erik@zededa.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
No functional changes; generated code and assets only. Signed-off-by: eriknordmark <erik@zededa.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
eriknordmark
force-pushed
the
document-api-capabilities
branch
from
August 7, 2026 21:51
2411b71 to
5eab836
Compare
eriknordmark
marked this pull request as ready for review
August 11, 2026 18:11
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A controller has no way to discover the
APICapabilitygates from the APIitself. The enum's comment describes it as covering "features in the
EdgeDevConfig", but it has grown to also cover messages EVE-OS sends — a
controller expecting S.M.A.R.T. information in
ZHardwareHealthfrom a devicebelow
API_CAPABILITY_SMART_REPORTwould wait for it indefinitely. The commentnow says both.
It also states explicitly that the enum is a monotonic level, to be compared
with
>=rather than tested for equality or set membership. EVE-OS reports asingle top value (
pkg/pillar/cmd/zedagent/reportinfo.goassignsAPI_CAPABILITY_REPORT_TPM_EVENTLOG), so a controller treating it as a flag setwould silently mishandle it. And it contrasts
OptionalCapabilities, which isthe opposite: independent booleans varying by build flavor rather than version.
Smaller fixes in the same area:
OptionalCapabilities.hw_inventory_supportwas the only field in its messagewithout a comment, and it is what tells a controller whether an empty
HardwareInventorymeans "found no hardware" or "cannot report".Capabilitiesmessage is now distinguished from theother two, since its comment previously read like a description of
APICapability.API_CAPABILITY_DISABLE_VTPMwas truncated at "Support for disabling", andAPI_CAPABILITY_VOLUME_SNAPSHOTS_IMMEDIATEduplicated value 5's comment.Wire-compatible: comments only. No field numbers, names or types change.
make protoproduces norawDescchurn and no Python change — only Go doccomments, in the second commit.