Publish schema compatibility data

.github/workflows/docs.yml

@@ -53,6 +53,7 @@ jobs:
               - 'docs/**'
               - 'extern/**'
               - 'examples/**'
+              - 'scripts/schema/**'
               - 'spack_repo/**'
               - '.github/workflows/docs.yml'
       - name: Decide whether to build

CHANGELOG.md

@@ -19,6 +19,9 @@ See the [developer notes on schema versioning](https://awslabs.github.io/palace/
 
 #### New Features
 
+  - Added machine-readable schema compatibility data to the installed schema files and
+    generated the developer documentation table from the same source
+    [PR 881](https://github.com/awslabs/palace/pull/881).
   - Improve BoundaryMode linear solver convergence when lossy boundary conditions are present
     by including complex terms in the real-valued preconditioner, or using an exact
     complex-valued preconditioner when `"ComplexCoarseSolve"` is true. Numeric wave ports

Makefile

@@ -4,7 +4,8 @@
 CLANG_FORMAT ?= clang-format
 JULIA ?= julia
 
-.PHONY: format format-cpp format-jl docs tests
+.PHONY: format format-cpp format-jl docs docs-generate-config \
+	docs-generate-schema-compatibility tests
 
 # Style/format
 format: format-cpp format-jl
@@ -24,6 +25,9 @@ docs:
 docs-generate-config:
 	$(JULIA) --project=docs --color=yes docs/generate_config_docs.jl
 
+docs-generate-schema-compatibility:
+	$(JULIA) --project=docs --color=yes docs/generate_schema_compatibility.jl
+
 # Tests
 #
 # Runs the [Regression] cases against an existing CMake build tree.

cmake/EmbedSchema.cmake

@@ -14,8 +14,9 @@ endif()
 
 file(MAKE_DIRECTORY ${SCHEMA_OUTPUT_DIR})
 
-# Collect all schema files
-file(GLOB SCHEMA_FILES "${SCHEMA_DIR}/*.json")
+# The directory also contains machine-readable schema release metadata, which is
+# distributed but is not itself a validation schema.
+set(SCHEMA_FILES "${SCHEMA_DIR}/config-schema.json")
 
 # Regenerate the header during build (not configure) when schema files change
 add_custom_command(

cmake/embed_schema.cmake

@@ -16,8 +16,9 @@ endif()
 get_filename_component(SCHEMA_OUTPUT_DIR "${SCHEMA_HEADER}" DIRECTORY)
 file(MAKE_DIRECTORY "${SCHEMA_OUTPUT_DIR}")
 
-# Collect all schema files
-file(GLOB SCHEMA_FILES "${SCHEMA_DIR}/*.json")
+# Embed only the validation schema. Other JSON files in this directory contain
+# distribution metadata rather than JSON Schemas.
+set(SCHEMA_FILES "${SCHEMA_DIR}/config-schema.json")
 
 # Generate the header file
 set(SCHEMA_HEADER_CONTENT

docs/generate_schema_compatibility.jl

@@ -0,0 +1,77 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Updates the schema compatibility table in docs/src/developer/notes.md from the
+# machine-readable data in scripts/schema/schema-compatibility.json.
+
+using JSON
+
+const COMPATIBILITY_PATH =
+    joinpath(@__DIR__, "..", "scripts", "schema", "schema-compatibility.json")
+const NOTES_PATH = joinpath(@__DIR__, "src", "developer", "notes.md")
+const TABLE_BEGIN = "```@raw html\n<!-- BEGIN GENERATED SCHEMA COMPATIBILITY TABLE -->\n```"
+const TABLE_END = "```@raw html\n<!-- END GENERATED SCHEMA COMPATIBILITY TABLE -->\n```"
+
+function markdown_row(values::Vector{String}, widths::Vector{Int})::String
+    return "| " *
+           join([rpad(value, width) for (value, width) in zip(values, widths)], " | ") *
+           " |"
+end
+
+function compatibility_table(entries::Vector)::String
+    isempty(entries) && error("Schema compatibility data must contain at least one entry")
+
+    rows = Vector{String}[]
+    for (index, entry) in enumerate(entries)
+        fields = ["schema_version", "first_palace_release", "notes"]
+        for field in fields
+            haskey(entry, field) ||
+                error("Compatibility entry $index is missing \"$field\"")
+            entry[field] isa String ||
+                error("Compatibility entry $index field \"$field\" must be a string")
+        end
+        push!(
+            rows,
+            [
+                "`$(entry["schema_version"])`",
+                "`$(entry["first_palace_release"])`",
+                entry["notes"]
+            ]
+        )
+    end
+
+    headers = ["Schema version", "First *Palace* release", "Notes"]
+    widths = [maximum(length(row[i]) for row in [headers, rows...]) for i = 1:3]
+    separators = [":" * repeat("-", width) * ":" for width in widths]
+    separators[3] = ":" * repeat("-", widths[3]) * " "
+
+    lines = [markdown_row(headers, widths), "|" * join(separators, "|") * "|"]
+    append!(lines, markdown_row(row, widths) for row in rows)
+    return join(lines, "\n")
+end
+
+function generate_schema_compatibility_table(;
+    compatibility_path::String=COMPATIBILITY_PATH,
+    notes_path::String=NOTES_PATH
+)
+    data = JSON.parsefile(compatibility_path)
+    haskey(data, "schema_versions") ||
+        error("Compatibility data is missing the \"schema_versions\" array")
+    data["schema_versions"] isa Vector ||
+        error("Compatibility data field \"schema_versions\" must be an array")
+
+    source = read(notes_path, String)
+    length(findall(TABLE_BEGIN, source)) == 1 ||
+        error("Expected exactly one compatibility table start marker in $notes_path")
+    length(findall(TABLE_END, source)) == 1 ||
+        error("Expected exactly one compatibility table end marker in $notes_path")
+
+    generated = "$TABLE_BEGIN\n\n$(compatibility_table(data["schema_versions"]))\n\n$TABLE_END"
+    pattern = Regex("(?s)" * TABLE_BEGIN * ".*?" * TABLE_END)
+    write(notes_path, replace(source, pattern => generated))
+    @info "Generated schema compatibility table in $notes_path"
+end
+
+if abspath(PROGRAM_FILE) == @__FILE__
+    generate_schema_compatibility_table()
+end

docs/make.jl

@@ -58,6 +58,10 @@ include(joinpath(@__DIR__, "generate_config_docs.jl"))
 generate_all()
 @info "Configuration documentation generated from JSON schemas."
 
+# Generate the human-readable schema compatibility table from its JSON source.
+include(joinpath(@__DIR__, "generate_schema_compatibility.jl"))
+generate_schema_compatibility_table()
+
 git_ref = get_git_ref()
 @info "Building documentation with GitHub links pointing to: $git_ref"
 rewrite_github_links(joinpath(@__DIR__, "src"), git_ref)

docs/src/developer/notes.md

@@ -222,14 +222,25 @@ numerically to *Palace*'s release version. The coupling is one-directional:
     not bump the schema version.
 
 Because the schema is versioned independently, a single schema version generally spans
-several *Palace* releases. The table below records the schema version shipped by each
-*Palace* release; a listed version applies from that release until the next row. Add a
-row when a release is cut, recording the schema version at that boundary.
+several *Palace* releases. The table below records the first *Palace* release shipping
+each schema version; a schema version applies to that release and all later ones up to
+(but not including) the next entry. Its source is the machine-readable
+[`schema-compatibility.json`](https://github.com/awslabs/palace/blob/main/scripts/schema/schema-compatibility.json)
+file. Add an entry there whenever a release introduces a new schema version; the
+documentation build generates this table from that file.
 
-| Schema version | *Palace* release | Notes                              |
-|:--------------:|:----------------:|:---------------------------------- |
-| `1-0-0`        | `0.17`           | First explicitly-versioned schema. |
-| `1-6-0`        | `0.18`           |                                    |
+```@raw html
+<!-- BEGIN GENERATED SCHEMA COMPATIBILITY TABLE -->
+```
+
+| Schema version | First *Palace* release | Notes                              |
+|:--------------:|:----------------------:|:---------------------------------- |
+| `1-0-0`        | `0.17.0`               | First explicitly-versioned schema. |
+| `1-6-0`        | `0.18.0`               |                                    |
+
+```@raw html
+<!-- END GENERATED SCHEMA COMPATIBILITY TABLE -->
+```
 
 #### When and how to bump (PR checklist)
 
@@ -264,9 +275,9 @@ schema version bump in that same PR. This means the repository will accumulate m
 
     Place the entry in the section that best describes the *motivation* (typically `New Features` for additions, `Interface Changes` for breaking changes).
 
- 4. Do NOT update the version table in this file (`docs/src/developer/notes.md`).
-    The table maps schema versions to *Palace* releases and is updated only when a release
-    is cut, not per-PR.
+ 4. Do NOT update `scripts/schema/schema-compatibility.json`.
+    The compatibility data maps schema versions to *Palace* releases and is updated only
+    when a release is cut, not per-PR.
 
 ##### Example changelog entry
 

scripts/check-schema-version

@@ -77,8 +77,8 @@ if [[ "${BASE_VERSION}" == "${HEAD_VERSION}" ]]; then
     echo "Error: schema files changed but '\$id' version was not bumped (still ${HEAD_VERSION})."
     echo "Changed files:"
     echo "${CHANGED}" | while IFS= read -r file; do echo "  ${file}"; done
-    echo "Bump the version in the '\$id' URN in ${ROOT_SCHEMA} and add a row to the version"
-    echo "table in docs/src/developer/notes.md. See the 'Schema versioning' section for the policy."
+    echo "Bump the version in the '\$id' URN in ${ROOT_SCHEMA} and add a SchemaVer entry"
+    echo "to CHANGELOG.md. See the 'Schema versioning' section in the developer notes."
     exit 1
 fi
 

scripts/schema/schema-compatibility.json

@@ -0,0 +1,14 @@
+{
+  "schema_versions": [
+    {
+      "schema_version": "1-0-0",
+      "first_palace_release": "0.17.0",
+      "notes": "First explicitly-versioned schema."
+    },
+    {
+      "schema_version": "1-6-0",
+      "first_palace_release": "0.18.0",
+      "notes": ""
+    }
+  ]
+}