Add a ballot changelog and a previous-version note - #393
Open
johngrimes wants to merge 8 commits into
Open
Conversation
Set the guide's version to 3.0.0-ballot with releaseLabel ballot, and describe the forthcoming publication in publication-request.json: sequence STU 3, status ballot, path http://hl7.org/fhir/uv/sql-on-fhir/2026Sep. The previous request described 2.0.0 at sequence R2 with a path the release was never published to. Disable automatic previous-version comparison. The publisher resolves the prior release through the package identifier in package-list.json, so it cannot reach 2.0.0, which shipped as org.sql-on-fhir.ig.
Publish a Changes page stating what breaks for an implementer upgrading from published 2.0.0: the canonical base and package identifier move, the ViewDefinition.identifier cardinality change, and the corrected sql-expressions invariant. Each entry states the migration action. A note covers readers who tracked the continuous build, where operation canonical URLs changed form but OperationDefinition.code did not. The delta is hand-authored because the publisher's automatic previous-version comparison cannot bridge the package rename. Define "canonical URL" and "package identifier" in the glossary, since the breaking changes are stated entirely in those terms. Declaring the page list is what allows the standards status to be set on the Changes page. SUSHI stops auto-generating page entries once any are declared, so all nine appear, with the titles it derived previously.
A reader arriving from a bookmark or a citation of the old canonical needs to know immediately that the guide moved namespace and that 2.0.0 is still available where it was. The generated version banner cannot say this, because it has no notion of the old canonical. The note uses the template's stu-note styling and sits above the existing lineage sentence, which is unchanged.
Four entries cited an issue that described a later refinement rather than the change the entry claimed. The operation entries now describe the addition and cite each tracker item for what it actually covers, and the terminology entry names the code systems and value sets against the issues that introduced them.
The async alignment cited #368, which is the still-open follow-up to replace a branch build link, rather than #369 which made the change. An audit of all 32 citations after that finding turned up two more places where the prose and the links had drifted: the cross-operation entry listed five of the six inconsistencies it linked, and the editorial entry led with #300, which covers the index page's query and API sections rather than the copy edits it claimed.
The round-1 audit compared each citation's title against the entry's claim, which was not enough. Checking diffs and dates instead found seven problems. The reviewer found three: $sqlquery-run led with #318, opened the day after #309 merged and about parameter alignment rather than the addition; the editorial entry led with #275, which touched one file rather than the narrative pages generally; and the terminology entry credited #309 with LibraryTypesCodes, which arrived in #293. Re-auditing by diff found four more: OutputFormatCodes and ExportStatusCodes arrived with the operations rather than with #331; the relicensing cited #261, whose body asks for something else entirely; the cnl-0 and dom-6 entry cited #377, which does not mention either constraint; and the relocation entry led with a commit that only updates prose URLs. Two entries that previously had no anchor for the operation's addition, only for its later refinements, now cite the commit that introduced the OperationDefinitions.
The output format entry was wrong on all three of its claims. The value sets are shared by family rather than per operation, with the run operations binding OutputFormatCodes and the export operations ExportOutputFormatCodes; ExportStatusCodes binds the export status parameter and has nothing to do with output formats; and the ExportStatusCodes code system arrived in #293 rather than with the operations. 340dce5 formalised the two $viewdefinition operations as OperationDefinitions, it did not add them. Both were specified in prose on the API page in 760f8f6, seven months earlier, so the lead citation belongs there.
The output format entry claimed #331 bound each operation's format parameter to a value set of the formats it supports, rather than leaving it open. Neither half holds. The bindings arrived with the operations in 340dce5, five months before #331 was filed, and the issue's own body says so. #331 proposed per-operation value sets that were never created, and its closing comment records that the project went the opposite way: the formats are split by operation kind, by PR #365.
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.
Addresses the review feedback in #380: if the major version is being incremented, the specification needs to say what is breaking, link the earlier specifications from a changelog, and point readers at the previous version.
The guide now declares
3.0.0-ballotwithreleaseLabel: ballot, andpublication-request.jsondescribes the September 2026 ballot at sequence STU 3. A new Changes page states the delta from published 2.0.0, opening with the three non-compatible changes and the migration action for each: the canonical base and package identifier move (#377),ViewDefinition.identifierbecoming repeating through theCanonicalResourcederivation, and the correctedsql-expressionsinvariant. The home page opens with a note telling a reader arriving from the old canonical where 2.0.0 still lives. The glossary gains "canonical URL" and "package identifier", since the breaking changes are stated entirely in those terms.The delta is hand-authored because the IG Publisher resolves the previous release through the package identifier in
{canonical}/package-list.json, so it cannot reach 2.0.0, which shipped asorg.sql-on-fhir.ig.version-comparisonis set ton/afor the same reason. Thepages:block is declared in full because setting a standards status on the Changes page needs a page-level extension, and SUSHI stops auto-generating entries once any are declared.CI will fail, for pre-existing reasons
The build reports 37 errors and 18 warnings, all present on
mainat c1da9a8 and none introduced here; that commit's own CI run fails with the same counts. 36 errors and all 18 warnings come from the IG Publisher deep-validating the ViewDefinition examples under the HL7 canonical (#377, diagnosed in #382); the remaining error is the unregistered Jira specification artefact (#388). Broken links are zero, andinput/ignoreWarnings.txtis byte-identical to c1da9a8.Merging accepts a documented pre-existing failure rather than a regression.
Out of scope
FHIR/sql-on-fhir.js still hardcodes the
sql-on-fhir.orgcanonicals across 35 files, which needs a companion issue before the ballot closes. Carrying the 2.0.0 entry into the new package's published history needs raising with the Product Director, aspackage-list.jsonis maintained by the publication process and this repository has no field for a historical entry. 2.0.0's own banner sits outside HL7's publication process and cannot be corrected.