Skip to content

Improve terminology, add external references and lifecycle docs (Issue-77) - #82

Merged
JoseMConde merged 6 commits into
camaraproject:mainfrom
DLondonoD:fix/issue-77
Sep 9, 2026
Merged

Improve terminology, add external references and lifecycle docs (Issue-77)#82
JoseMConde merged 6 commits into
camaraproject:mainfrom
DLondonoD:fix/issue-77

Conversation

@DLondonoD

@DLondonoD DLondonoD commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

documentation

What this PR does / why we need it:

Improves documentation and property naming per issue #77, which noted that external
terminology has no references, the end-to-end lifecycle isn't documented, some
property names are over-abbreviated or inconsistent, and two tags are unused.

  • Added a "Terminology and external references" section linking domain terms
    (Kubernetes, Helm, Docker Compose, QCOW2/OVA, CSAR, CNI, SR-IOV, CloudEvents, ISO
    3166-1 alpha-2, RFC 3339/3986) to authoritative external specs, plus an inline RFC
    3986 link on the Uri schema.
  • Added an "Application Lifecycle" section walking through a typical end-to-end use
    of the API, from submitApp to deleteApp.
  • Fixed the naming inconsistency the issue called out explicitly: ClusterInfo. clusterRef and getEdgeCloudZones' clusterRef query parameter are now both
    kubernetesClusterRef, matching every other occurrence of this identifier throughout
    the API.
  • Renamed K8sAddons/K8sNetworking to KubernetesAddons/KubernetesNetworking,
    and AppManifest.appRepo to AppManifest.repository (redundant "app" prefix on a
    property already nested under AppManifest), for friendlier, less abbreviated names.
  • Renamed infraKind to infrastructureKind (the discriminator on
    RequiredResources and its 4 implementations) for the same reason.
  • Removed the two unused App Instance CALLBACK Operation/App Deployment CALLBACK Operation tags: they only ever showed up in the tags: list of operations nested
    under callbacks:, which API doc renderers (ReDoc/Swagger UI) don't group by tag, so
    they rendered as empty tag groups.
  • Updated the .feature files referencing appRepo and clusterRef accordingly
    (getApp, submitApp, getEdgeCloudZones).

Not done / left as-is, intentionally:

  • The App/app prefix used throughout operation IDs, paths and schema names
    (appId, AppInstanceId, /apps, createAppInstance, etc.) was not renamed.
    It's a well-understood, consistently-applied convention rather than an unclear
    abbreviation, and changing it would touch the entire API surface for comparatively
    little clarity gain. Happy to revisit if reviewers disagree.
  • No behavioral change: all changes are renames, added descriptions/links, or
    removal of unused metadata (tags). No schema semantics, request/response codes, or
    test scenario coverage were altered beyond following the renamed properties.

Which issue(s) this PR fixes:

Fixes #77

Special notes for reviewers:

Branched from fix/issue-75 (not yet merged to main), so this PR's diff includes
that branch's changes too until it lands; please review/merge #81 (issue #75) first
if still pending.

The infraKind/appRepo/clusterRef/K8s* renames are breaking changes to the
request/response schemas (property names change). Since this API is still wip/pre-
release (no published stable version), this seemed like the right time to make them;
flagging in case that assumption should be revisited.

Changelog input

release-note Renamed ClusterInfo.clusterRef and getEdgeCloudZones' clusterRef query
parameter to kubernetesClusterRef for consistency; renamed K8sAddons/K8sNetworking to
KubernetesAddons/KubernetesNetworking, AppManifest.appRepo to AppManifest.repository,
and infraKind to infrastructureKind for clarity. Removed unused CALLBACK tags. Added
external terminology references and an end-to-end Application Lifecycle section to
the API description.

Additional documentation

docs

@DLondonoD
Improve terminology, add external references and lifecycle docs (cama…
67354bb 
…raproject#77)

Per issue camaraproject#77, the API lacked external references for domain
terminology, an end-to-end lifecycle walkthrough, and had inconsistent
or over-abbreviated property names plus unused tags.

- Added a "Terminology and external references" section linking
  Kubernetes, Helm, Docker Compose, QCOW2/OVA, CSAR, CNI, SR-IOV,
  CloudEvents, ISO 3166-1 alpha-2 and RFC 3339/3986 to authoritative
  external specs, and an inline RFC 3986 link on the Uri schema.
- Added an "Application Lifecycle" section walking through a typical
  end-to-end use of the API, from submitApp to deleteApp.
- Fixed the naming inconsistency the issue called out explicitly:
  ClusterInfo.clusterRef and getEdgeCloudZones' clusterRef query
  parameter are now both kubernetesClusterRef, matching every other
  occurrence of this identifier throughout the API.
- Renamed K8sAddons/K8sNetworking to KubernetesAddons/
  KubernetesNetworking, and AppManifest.appRepo to
  AppManifest.repository (redundant "app" prefix on a property
  already nested under AppManifest), for friendlier, less abbreviated
  names.
- Renamed infraKind to infrastructureKind (the discriminator on
  RequiredResources and its 4 implementations) for the same reason.
- Removed the two unused "App Instance CALLBACK Operation"/"App
  Deployment CALLBACK Operation" tags, which only ever showed up as
  the tags: list is not picked up by API doc renderers (ReDoc/Swagger
  UI) for operations nested under callbacks:, so they rendered as
  empty tag groups.
- Updated the .feature files referencing appRepo and clusterRef
  accordingly (getApp, submitApp, getEdgeCloudZones).

Left the "App"/"app" prefix used throughout operation IDs, paths and
schema names (appId, AppInstanceId, /apps, createAppInstance, etc.)
untouched, as it is a well-understood, consistently-applied convention
rather than an unclear abbreviation, and renaming it would touch the
entire API surface for comparatively little clarity gain.
seralogar
seralogar reviewed Sep 8, 2026
View reviewed changes
Comment thread code/API_definitions/edge-application-management.yaml Outdated
Comment thread code/API_definitions/edge-application-management.yaml
@DLondonoD
Fix terminology references per @seralogar's PR camaraproject#82 review
41a03c5 
- Recategorized the "Docker Compose" bullet: it's not a packageType
  (the enum is QCOW2/OVA/CONTAINER/HELM/CSAR), it's
  requiredResources.infrastructureKind: dockerCompose /
  DockerComposeResources. Added the missing CONTAINER packageType
  reference (OCI Image Format Specification) to fill the gap this
  left, in both the terminology section and the packageType
  description.
- Fixed the QCOW2 reference to actually point at QEMU's own qcow2
  format documentation instead of the OpenStack image guide
  introduction page, in both the terminology section and the
  packageType description.
- Fixed the SR-IOV reference: PCI-SIG specs are members-only/paywalled,
  so linking a Linux kernel driver howto and labeling it "PCI-SIG SR-IOV
  overview" misattributed the source. Replaced with Intel's "PCI-SIG
  SR-IOV Primer" technical paper, which is freely accessible and
  correctly attributes the SR-IOV specification to PCI-SIG.
- Fixed the TOSCA reference to point at the actual OASIS TOSCA v2.0
  specification document instead of the committee landing page, in
  both the terminology section and the packageType description.
- Unified the ISO 3166-1 alpha-2 reference URL: the terminology
  section and the CountryCode schema description pointed at two
  different ISO OBP URLs (#search/code/ vs #search) for the same
  reference; both now use #search/code/, the one ISO's own site links
  to for country code lookups.
@DLondonoD
Polish terminology references wording and links
410e7f8 
- Dropped the redundant "not a packageType" aside on the Docker
  Compose bullet; the distinction is already covered by the
  "Kubernetes vs. compute/memory/storage applications" section.
- Pointed the SR-IOV reference at Intel's HTML landing page for the
  PCI-SIG SR-IOV primer instead of the direct PDF, for easier browsing.
@DLondonoD
Fix S-011 warnings: missing descriptions on deployment array properties
665cbae 
CAMARA validation flagged AppDeploymentZoneRequest.edgeCloudZones and
AppDeploymentClusterRequest.kubernetesClusterRefs for missing a
description (S-011), unlike their AppDeploymentInfo counterparts.
Added descriptions consistent with the existing AppDeploymentInfo
wording.
seralogar
seralogar previously approved these changes Sep 8, 2026
View reviewed changes
@DLondonoD
DLondonoD dismissed seralogar’s stale review September 8, 2026 16:10

The merge-base changed after approval.

seralogar
seralogar previously approved these changes Sep 8, 2026
View reviewed changes
@DLondonoD
DLondonoD dismissed seralogar’s stale review September 8, 2026 16:17

The merge-base changed after approval.

seralogar
seralogar previously approved these changes Sep 8, 2026
View reviewed changes
JoseMConde
JoseMConde approved these changes Sep 9, 2026
View reviewed changes

@JoseMConde JoseMConde left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@JoseMConde
JoseMConde merged commit a75200d into camaraproject:main Sep 9, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@JoseMConde JoseMConde JoseMConde approved these changes
@seralogar seralogar seralogar left review comments
@Kevsy Kevsy Awaiting requested review from Kevsy Kevsy is a code owner
@FabrizioMoggio FabrizioMoggio Awaiting requested review from FabrizioMoggio FabrizioMoggio is a code owner
@gainsley gainsley Awaiting requested review from gainsley gainsley is a code owner
@maheshc01 maheshc01 Awaiting requested review from maheshc01 maheshc01 is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

General documentation and terminology improvements

3 participants

@DLondonoD @seralogar @JoseMConde