Repository navigation
[#231] Rename the Protocol Buffers namespace to spPv4.0 - #654
wes-johnson wants to merge 2 commits into
Conversation
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
left a comment
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
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-idset is identical (664); - all 57
payloads_c_*anchors map one-for-one topayloads_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
left a comment
There was a problem hiding this comment.
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.
|
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 The missing rule (Nathan). The specification now states what the rename implies, which it did not say anywhere:
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). Verification: build successful; broken-anchor (11) and tck-id-anomaly (7) baselines unchanged; no |
|
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 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:
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. |
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 —
Pfor Google Protocol Buffers alongsideJfor JSON — rather than continuing the A, B, C sequence of encoding scheme generations.The change
spCv4.0→spPv4.0Sparkplug C→Sparkplug Ppayloads_c_*→payloads_p_*link:#referencesSections.PAYLOADS_C_*→PAYLOADS_P_*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 asSparkplug Cbeside aspPv4.0token 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_metricbecomes…#payloads_p_metric. No released specification contains them: Sparkplug 3.0.0 usespayloads_b_*, andpayloads_c_*only ever existed ondevelop, 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 —Sectionsconstants feed@SpecAssertionannotations 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:
Sectionsis 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_componentsnamed the wrong encoding for a section titled "Sparkplug B v1.0 Payload Components". It is nowpayloads_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_orSparkplug Cremains in any tracked file. Every one of the 15 distinctSectionsconstants used by the TCK was checked to have a renamed counterpart in the generated source before the references were changed.git diff --checkclean; the diff is 372 insertions and 372 deletions, one-for-one.