Skip to content

[#231] Rename the Protocol Buffers namespace to spPv4.0 - #654

Open
wes-johnson wants to merge 2 commits into
eclipse-sparkplug:developfrom
wes-johnson:231-sppv4
Open

wes-johnson wants to merge 2 commits into
eclipse-sparkplug:developfrom
wes-johnson:231-sppv4

Conversation

@wes-johnson

Copy link
Copy Markdown
Contributor

Closes the namespace-letter question left open on #231.

The working group chose spPv4.0 over spCv4.0, so the letter in the token names the payload encoding — P for Google Protocol Buffers alongside J for JSON — rather than continuing the A, B, C sequence of encoding scheme generations.

The change

spCv4.0 → spPv4.0 135 occurrences across the specification, the PlantUML source and the 4.0.0 release plan
Sparkplug C → Sparkplug P the scheme name, so it agrees with its token
payloads_c_* → payloads_p_* 122 anchors and link:# references
Sections.PAYLOADS_C_* → PAYLOADS_P_* 112 references in the TCK

The scheme rename follows from the token. Chapter 1 presents the schemes as a sequence whose members each carry a matching token (Sparkplug A → spAv1.0, Sparkplug B → spBv1.0), so leaving the name as Sparkplug C beside a spPv4.0 token would have broken that correspondence in the one place the specification explains it.

Deep links change, but little depends on them. The payloads_c_* anchors are fragment identifiers in the rendered specification, so a link to …#payloads_c_metric becomes …#payloads_p_metric. No released specification contains them: Sparkplug 3.0.0 uses payloads_b_*, and payloads_c_* only ever existed on develop, introduced during v4 work in b8007f7. The only links that can break are into milestone builds or previews of the draft.

What does not change is tck-id-*. I diffed this commit for assertion identifiers added or removed and found none either way, so conformance results stay comparable and implementers' references to assertions keep working. That is the identifier people actually depend on. The 3.0.0 specification is on a separate branch and untouched, and TCK behaviour is unaffected — Sections constants feed @SpecAssertion annotations internally, and third parties run the TCK rather than compile against it. The one residual effect is cosmetic: TCK coverage reports label sections by these names, so a report generated after this change shows renamed section headings. No assertion moves and nothing is scored differently.

The TCK change is a consequence, not a choice: Sections is generated from the anchor names, so renaming the anchors renames the constants and every reference to them had to follow. Nothing in the TCK's behaviour changes.

One drive-by: payloads_c_sparkplug_cv1_0_payload_components named the wrong encoding for a section titled "Sparkplug B v1.0 Payload Components". It is now payloads_p_sparkplug_bv1_0_payload_components.

What is not in here

The TCK still publishes and subscribes on spBv1.0 — that is #641, and it is unaffected by this rename.

Verification

Build successful. Broken-anchor (11) and tck-id-anomaly (7) baselines unchanged against develop. JSON Schema valid draft 2020-12, 22/22 chapter examples validate. No spCv4.0, payloads_c_, PAYLOADS_C_ or Sparkplug C remains in any tracked file. Every one of the 15 distinct Sections constants used by the TCK was checked to have a renamed counterpart in the generated source before the references were changed. git diff --check clean; the diff is 372 insertions and 372 deletions, one-for-one.

The working group chose spPv4.0 over spCv4.0, so the letter in the
token names the payload encoding - 'P' for Google Protocol Buffers
alongside 'J' for JSON - rather than continuing the A, B, C sequence
of encoding scheme generations.

- spCv4.0 becomes spPv4.0 throughout the specification, the PlantUML
  source and the 4.0.0 release plan (135 occurrences).
- The encoding scheme is renamed from 'Sparkplug P' accordingly, so
  the scheme name and its token agree.
- The payloads_c_* anchor family becomes payloads_p_* (122
  occurrences). These are the fragment identifiers of the published
  specification, so deep links to a section change.
- Sections constants are generated from those anchors, so the 112
  Sections.PAYLOADS_C_* references in the TCK become PAYLOADS_P_*.
- payloads_c_sparkplug_cv1_0_payload_components named the wrong
  encoding for a section titled 'Sparkplug B v1.0 Payload
  Components'; it is now payloads_p_sparkplug_bv1_0_payload_components.

@ckienle ckienle left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Approving. Every changed line is just the rename (spCv4.0, Sparkplug C, payloads_c_, PAYLOADS_C_), and nothing of the old names is left except the one letter noted inline at Introduction line 86.

@nathandavenport nathandavenport 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.

Reviewed at 9f9e236. Agree with the Introduction line 86 letter already raised inline. Beyond that, the rename is mechanical and complete:

  • every changed line is the declared substitution, plus the declared drive-by anchor;
  • the tck-id set is identical (664);
  • all 57 payloads_c_* anchors map one-for-one to payloads_p_*;
  • no xref is broken that wasn't already broken on develop;
  • all 15 Sections.PAYLOADS_P_* constants used by the TCK resolve to an anchor;
  • no stale token in any tracked image.

Optional (non-blocking), outside the diff: the extracted schema still carries the old letter in its filename. specification/build.gradle.kts:250 writes proto/sparkplug_c.proto, and the "To compile" comment at the top of the schema listing (Sparkplug_6_Payloads.adoc:124, extracted verbatim into that artifact) says ../../sparkplug_c.proto. The TCK consumes the artifact as a single file, without the name (specification/build.gradle.kts:289), so renaming both to sparkplug_p.proto is a two-line change with no knock-on.

@nathandavenport nathandavenport 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.

Approved with two non-blocking comments added.

…e schema filename

- The Payload Encoding Scheme bullet still listed the letters as 'A',
  'B', 'C', or 'J'. My sweep searched for spCv4.0, Sparkplug C and the
  payloads_c_ identifiers, none of which match a bare quoted letter.
- States the rule the rename introduced, which the specification did
  not say anywhere: from version 4.0 the letter names the payload
  encoding rather than the generation of the scheme. Without it a
  reader sees 'first A, second B, most recent P' with no explanation,
  and 'P' can read as Protocol Buffers in general, which Sparkplug B
  also is.
- Renames the extracted schema artifact to sparkplug_p.proto, both in
  the task that writes it and in the 'To compile' comment carried
  verbatim into it. The TCK consumes the artifact as a single file
  without reference to its name.
- payloads_sparkplug_c_mqtt_payload_definition anchors a section titled
  'Sparkplug B MQTT Payload Definition', beside a sibling anchored
  payloads_sparkplug_a_. The letter was wrong before this PR; it is now
  payloads_sparkplug_b_mqtt_payload_definition.
@wes-johnson

Copy link
Copy Markdown
Contributor Author

Pushed 814c029, addressing all three comments.

The stale letter (Chad). The Payload Encoding Scheme bullet still read 'A', 'B', 'C', or 'J'. A real miss: my sweep searched for spCv4.0, Sparkplug C, payloads_c_ and PAYLOADS_C_ — the forms I had renamed — and none of them match a bare quoted letter. I re-swept afterwards for quoted letters, _c_ identifier fragments and cv1/cv4 fragments, which found one more: payloads_sparkplug_c_mqtt_payload_definition anchors a section titled "Sparkplug B MQTT Payload Definition", beside a sibling anchored payloads_sparkplug_a_. That letter was wrong before this PR and is now payloads_sparkplug_b_....

The missing rule (Nathan). The specification now states what the rename implies, which it did not say anywhere:

From version 4.0 the letter names the payload encoding rather than the generation of the encoding scheme: 'P' for Google Protocol Buffers and 'J' for JSON. 'A' and 'B' are the earlier schemes, which were lettered by generation.

The point that Sparkplug B is also Protocol Buffers, so a bare 'P' could read as the encoding in general, is what made the sentence necessary rather than merely helpful.

The schema filename (Nathan). specification/build.gradle.kts now writes proto/sparkplug_p.proto, and the "To compile" comment carried verbatim into that artifact names ../../sparkplug_p.proto. Verified by removing specification/build/proto and re-running extractProtoSchema: only sparkplug_p.proto is produced, with the corrected comment inside it.

Verification: build successful; broken-anchor (11) and tck-id-anomaly (7) baselines unchanged; no spCv4.0, Sparkplug C, payloads_c_, payloads_sparkplug_c_, PAYLOADS_C_, quoted 'C' or sparkplug_c.proto in any tracked file; git diff --check clean.

@nathandavenport

Copy link
Copy Markdown
Contributor

Thanks Wes. Checked 814c029: all three are in and read well. The letter list is fixed, the new bullet makes the P/J rule explicit and settles the "B is Protobuf too" ambiguity, and sparkplug_p.proto is in both places. Restoring payloads_sparkplug_b_mqtt_payload_definition also brings back the 3.0.0 anchor for that section, so old deep links resolve again. The tck-id set, the broken-link baseline and the TCK Sections constants are all unchanged.

One more for your judgement, now or in a follow-up. It predates this PR, so it isn't blocking. Two Chapter 6 headings still name the v4 Protobuf encoding as Sparkplug B:

  • Sparkplug_6_Payloads.adoc:69: "Sparkplug B MQTT Payload Definition". The JSON overview (line 3521) now points readers here for "the Google Protocol Buffers encoding ... published on the spPv4.0 namespace", and the new Chapter 1 bullet calls B an earlier scheme, so the mismatch is more visible than it was.
  • Sparkplug_6_Payloads.adoc:427: "Sparkplug B v1.0 Payload Components", which says it defines "the actual payload contents of each message type in Sparkplug B v1.0" (line 432).

The prose under them, and further into the chapter, uses "Sparkplug B" for the v4 objects too, e.g. Metric (746), MetaData (963), PropertySet (994), about 50 mentions in all. The Command section already says "Sparkplug P Command", so the chapter currently uses both names. If you take it on, renaming the headings would move their anchors off the 3.0.0 names you just restored, so it may suit a separate pass that settles the B/P wording for the whole chapter in one go.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants