Merge branch 'main' into comms-steps

Author: jonedmiston

.github/workflows/release.yml

@@ -77,9 +77,20 @@ jobs:
             exit 1
           fi
 
+          # A release's loader must load its own packages (decision 158).
+          if [ "$publish" = "true" ]; then
+            node release/check-minimum-loader.js --version "$version"
+          fi
+
           prerelease=false
           [[ "$version" == *-* ]] && prerelease=true
-          releases=$(jq -c '[.releases[] | { version, ref }]' release/rock-releases.json)
+
+          # One Rock release per major release, whose packages go under rock-{major} (decision 52).
+          releases=$(jq -c '[.releases[] | { version, ref, major: (.version | split(".")[0] | tonumber) }]' release/rock-releases.json)
+          if [ "$(jq '[.[].major] | length != (unique | length)' <<< "$releases")" = "true" ]; then
+            echo "::error::release/rock-releases.json lists two Rock releases for one major release."
+            exit 1
+          fi
           {
             echo "version=$version"
             echo "publish=$publish"
@@ -101,6 +112,7 @@ jobs:
         rock: ${{ fromJSON(needs.plan.outputs.releases) }}
     env:
       ROCK_VERSION: ${{ matrix.rock.version }}
+      ROCK_MAJOR: ${{ matrix.rock.major }}
       ROCK_REF: ${{ matrix.rock.ref }}
     steps:
       - uses: actions/checkout@v4
@@ -187,20 +199,21 @@ jobs:
       - name: Check SQL Server sign-in
         run: sqlcmd -S localhost -E -C -Q "SELECT @@VERSION, SUSER_SNAME() AS [Login], IS_SRVROLEMEMBER('sysadmin') AS [IsSysAdmin];"
 
+      # Each package serves every dot release of its major, so it is written and published under rock-{major}.
       - name: Write the packages
-        run: dotnet run --project builder -c Release -- --rock "$env:ROCK_PATH" --out "packages/rock-$env:ROCK_VERSION"
+        run: dotnet run --project builder -c Release -- --rock "$env:ROCK_PATH" --out "packages/rock-$env:ROCK_MAJOR"
 
       - name: Verify the packages
-        run: dotnet run --project verify -c Release -- --rock "$env:ROCK_PATH" --packages "packages/rock-$env:ROCK_VERSION" --run ci
+        run: dotnet run --project verify -c Release -- --rock "$env:ROCK_PATH" --packages "packages/rock-$env:ROCK_MAJOR" --run ci
 
       - name: Publishing gate
-        run: dotnet run --project verify -c Release --no-build -- --check-receipts "packages/rock-$env:ROCK_VERSION"
+        run: dotnet run --project verify -c Release --no-build -- --check-receipts "packages/rock-$env:ROCK_MAJOR"
 
       - uses: actions/upload-artifact@v4
         if: always()
         with:
-          name: rock-${{ matrix.rock.version }}
-          path: packages/rock-${{ matrix.rock.version }}
+          name: rock-${{ matrix.rock.major }}
+          path: packages/rock-${{ matrix.rock.major }}
           if-no-files-found: warn
           retention-days: 14
 

README.md

@@ -151,7 +151,7 @@ and push. Ask me before anything that removes or rewrites history.
 - **Every campus has businesses** that give, each with one or two contacts. The main campus has at least 6 and every other campus at least 2.
 - **Dates are generated at install**, counted back from install day, so "last 12 months" reports are always full.
 - **Realism is measured.** The same scripts that measure real churches grade our data. Today 91% of measured values fall within tolerance, including serving, connections, and prayer.
-- **Correctness is proven against Rock itself.** Before a package is published, the verify tool loads it into a clean copy of its exact Rock release, checks it against Rock's schema, runs rule checks, and has Rock's own Rock Cleanup job look for anything to fix. See [Verification](docs/verification.md).
+- **Correctness is proven against Rock itself.** Before a package is published, the verify tool loads it into a clean copy of the Rock release it is built on, checks it against Rock's schema, runs rule checks, and has Rock's own Rock Cleanup job look for anything to fix. See [Verification](docs/verification.md).
 - **People have notes** in six note types, secured to staff. Cast notes are hand-written and tied to each family's story, and they show more and better note use than most churches have today.
 - **A building campaign is under way.** Built on the Rock is about 38% through on install day, with pledges from people and businesses in every state Pledge Analytics can show.
 - **Giving analytics work on install.** Giving attributes, journey stages, and a year of giving alerts are filled in the way Rock computes them, and a version guard catches Rock changing that math.
@@ -171,7 +171,7 @@ and push. Ask me before anything that removes or rewrites history.
 | [builder/](builder/README.md) | The .NET tool that turns this repository into one dataset package per dataset. |
 | [loader/](loader/README.md), `loader-cli/`, `loader-compat-check/` | The loader library that installs a package into a Rock database (for .NET 10 and for Rock's .NET Framework, as the `SparkDevNetwork.Rock.SampleData.Loader` NuGet package), its command line for developers and test harnesses, and the check that both builds compute the same keys. |
 | [validation/](validation/README.md) | Tolerances and the script that grades generated data, plus the invariants, contract, and standards check the verify tool uses. |
-| [verify/](verify/README.md) | The tool that proves each package works on one exact Rock and writes its receipt. Publishing needs a passing receipt. |
+| [verify/](verify/README.md) | The tool that proves each package works on the Rock it is built on and writes its receipt. Publishing needs a passing receipt. |
 | [release/](release/README.md) | The Rock releases each release builds for, and the script that merges a release into the hosted package index. `.github/workflows/release.yml` publishes the packages and the loader on a version tag. How to release, what has shipped, and how to fix a failed run: [Publishing a release](docs/maintaining.md#publishing-a-release). |
 | [datasets/](datasets/README.md) | One manifest per dataset, with its settings. |
 | [content/](content/README.md) | Fonts for check images, and later the text pools. |
@@ -194,11 +194,11 @@ You need the .NET 10 SDK, Node.js 20 or later, and SQL Server with a freshly ins
    dotnet run -- --rock C:\Development\Rock
    ```
 
-3. Load Core 1 into a fresh Rock database. Add `--dry-run` to roll everything back at the end. If your database is on a different migration than the checkout, add `--any-rock`.
+3. Load Core 1 into a fresh Rock database. `--rock` names your built Rock checkout, so the loader can read its version from `RockWeb\bin\Rock.Version.dll`. Add `--dry-run` to roll everything back at the end. If your database is on another Rock major release than the checkout, add `--any-rock`.
 
    ```
    cd ../loader-cli
-   dotnet run -- --package ../packages/core-1.zip --connection "Server=localhost;Database=RockSample;Integrated Security=true;TrustServerCertificate=true"
+   dotnet run -- --package ../packages/core-1.zip --rock C:\Development\Rock --connection "Server=localhost;Database=RockSample;Integrated Security=true;TrustServerCertificate=true"
    ```
 
 4. Grade the result against the profile. See [Validation](validation/README.md) for the three commands.

builder/PackageWriter.cs

@@ -144,8 +144,9 @@ void AddFolder( string folder, string extension = null )
             files["README.md"] = Normalize( "README.md", Utf8( repository.ReadText( "builder/package-readme.md" )
                 .Replace( "{{name}}", datasetManifest.Name )
                 .Replace( "{{dataset}}", dataset )
+                .Replace( "{{rockMajor}}", rock?.Major.ToString() ?? "(unknown)" )
                 .Replace( "{{rockVersion}}", rock?.Version ?? "(unknown)" )
-                .Replace( "{{rockMigration}}", rock?.Migration ?? "(unknown)" ) ) );
+                .Replace( "{{minimumLoaderVersion}}", SampleDataPackage.MinimumLoaderVersion ) ) );
 
             var manifest = new PackageManifest
             {
@@ -154,7 +155,8 @@ void AddFolder( string folder, string extension = null )
                 Name = datasetManifest.Name,
                 Profile = profileName,
                 Source = ReadSource( root ),
-                Rock = rock
+                Rock = rock,
+                MinimumLoaderVersion = SampleDataPackage.MinimumLoaderVersion
             };
             foreach ( var (path, bytes) in files )
             {

builder/Program.cs

@@ -62,8 +62,9 @@ dotnet run -- --deliver-photos <batch.json> [--root <repository folder>]
     }
 }
 
-// Otherwise, write packages. Every package is for one exact Rock: the version and newest migration
-// come from a Rock checkout (--rock, or ROCK_PATH), or are given directly.
+// Otherwise, write packages. Every package is for one Rock major release (decision 52): the version,
+// whose first number is the major, and the newest migration come from a Rock checkout (--rock, or
+// ROCK_PATH), or are given directly.
 try
 {
     var rock = RockCheckout.Read(

builder/README.md

@@ -10,12 +10,12 @@ From the `builder` folder:
 dotnet run -- --rock C:\Development\Rock
 ```
 
-That writes every dataset's package to `../packages/` (git ignores it). Each package is for the Rock in the checkout you name.
+That writes every dataset's package to `../packages/` (git ignores it). Each package is for the major release of the Rock in the checkout you name, such as Rock 21, and serves every dot release of it (decision 52).
 
 | Option | Meaning |
 |---|---|
-| `--rock <folder>` | A Rock checkout. The package records its version (from `Directory.Build.props`) and its newest migration (from `Rock.Migrations/Migrations`). The `ROCK_PATH` environment variable does the same. Required unless both values below are given. |
-| `--rock-version` | The Rock version, for example `21.0.1`. Wins over the checkout's. |
+| `--rock <folder>` | A Rock checkout. The package records its version (from `Directory.Build.props`), whose first number is the major release, and its newest migration (from `Rock.Migrations/Migrations`). The `ROCK_PATH` environment variable does the same. Required unless both values below are given. |
+| `--rock-version` | The Rock version, for example `21.0.2`. Its first number is the package's major release. Wins over the checkout's. |
 | `--rock-migration` | The newest migration Id, for example `202609222138362_AddWorkflowBuilder`. Wins over the checkout's. |
 | `--dataset` | One dataset (`core-1`, `core-3`, or `full-7`), or `all` (the default). |
 | `--out <folder>` | Where to write packages. Defaults to `../packages`. |
@@ -28,7 +28,7 @@ A package is a zip of data, never SQL (decision 41). Files keep their paths from
 
 | Path | What it holds |
 |---|---|
-| `package.json` | The format version, the dataset, the source commit, the one Rock it is for (decision 52), and the SHA-256 of every other file. |
+| `package.json` | The format version, the dataset, the source commit, the Rock major release it is for and the exact Rock it was built on (decision 52), the oldest loader that can load it (decision 158), and the SHA-256 of every other file. |
 | `configuration/*.json` | The church setup, unchanged. |
 | `cast/households/*.json`, `cast/groups/*.json` | The Cast and its small group plans, unchanged. |
 | `datasets/{key}.json` | The dataset's settings and its [card](../datasets/README.md#the-dataset-card). |

builder/RockCheckout.cs

@@ -18,13 +18,15 @@
 using System.Text.RegularExpressions;
 using System.Xml.Linq;
 
+using RockSampleData.Loader;
 using RockSampleData.Loader.Packages;
 
 namespace RockSampleData.Builder
 {
     /// <summary>
-    /// Reads which Rock a package is for from a Rock checkout: the version in Directory.Build.props
-    /// and the newest Entity Framework migration in Rock.Migrations.
+    /// Reads which Rock a package is for from a Rock checkout: the version in Directory.Build.props,
+    /// whose first number is the major release the package serves (decision 52), and the
+    /// newest Entity Framework migration in Rock.Migrations.
     /// </summary>
     internal static class RockCheckout
     {
@@ -47,7 +49,9 @@ public static PackageRock Read( string checkoutPath, string version, string migr
                 throw new InvalidOperationException( "A package must say which Rock it is for. Pass --rock <Rock checkout> (or set ROCK_PATH), or both --rock-version and --rock-migration." );
             }
 
-            return new PackageRock { Version = version, Migration = migration };
+            var major = RockVersionInfo.MajorOf( version )
+                ?? throw new InvalidOperationException( $"The Rock version {version} does not start with a major release number, such as 21 in 21.0.2." );
+            return new PackageRock { Major = major, Version = version, Migration = migration };
         }
 
         /// <summary>

builder/package-readme.md

@@ -1,6 +1,6 @@
 # {{name}} sample data package
 
-This package installs the **{{name}}** dataset (`{{dataset}}`) of Rock Sample Data into a fresh Rock database. It is for Rock {{rockVersion}} (newest migration `{{rockMigration}}`). The loader refuses any other Rock.
+This package installs the **{{name}}** dataset (`{{dataset}}`) of Rock Sample Data into a fresh Rock database. It is for every Rock {{rockMajor}} release, and was verified on Rock {{rockVersion}}. The loader refuses any other major release of Rock. It needs loader {{minimumLoaderVersion}} or newer.
 
 All the people, families, and organizations in it are fictional.
 
@@ -17,7 +17,7 @@ The package holds the inputs, not the records. It has no attendance rows, gifts,
 | `addresses/pool.json` | Real-street addresses with house numbers that do not exist |
 | `photos/` | Profile photos, and a photo of each Cast small group |
 | `content/fonts/` | Fonts for the scanned check images, with their licenses |
-| `package.json` | The format version, the Rock this package is for, and a SHA-256 for every file |
+| `package.json` | The format version, the Rock major release this package is for, the oldest loader that can load it, and a SHA-256 for every file |
 | `LICENSE.md` | The license for this data |
 
 ## What the loader makes from it
@@ -52,7 +52,7 @@ The loader library (`RockSampleData.Loader`) and its command line both install p
 rock-sample-data-load --package {{dataset}}.zip --connection "<connection string>" [--anchor yyyy-MM-dd] [--seed text]
 ```
 
-Before it writes anything, the loader checks the format version, every file's SHA-256, that the database has no people beyond a new Rock install, and that it is Rock {{rockVersion}}. The load runs in one transaction, so a failure leaves nothing behind. Every row it writes carries `ForeignKey = SampleData:{{dataset}}`.
+Before it writes anything, the loader checks the format version, that it is loader {{minimumLoaderVersion}} or newer, every file's SHA-256, that the database has no people beyond a new Rock install, and that its Rock is a Rock {{rockMajor}} release. It reads Rock's version from `Rock.Version.dll`. The load runs in one transaction, so a failure leaves nothing behind. Every row it writes carries `ForeignKey = SampleData:{{dataset}}`.
 
 ## More
 

calibration/profiles/sample-church.json

@@ -48,6 +48,7 @@
     { "path": "communicationDetail.unsubscribesYear.perThousandMassRecipients.Recipient preference", "reason": "Too few unsubscribes to use." }
   ],
   "overrides": [
+    { "path": "people.ageMix", "value": { "00-05": 3.94, "06-11": 9.61, "12-17": 18.64, "18-24": 18.51, "25-34": 15.27, "35-44": 15.72, "45-54": 9.37, "55-64": 5.35, "65-74": 2.9, "75+": 0.78 }, "reason": "Assumption. The measured age mix counts only people with a birth date, and 17.9% of measured people have none (people.pctNoBirthDate), but every sample person has one (decision 156). These are the measured shares restated as shares of all people, assuming the people with no birth date are adults spread like the adults who have one: each child band is the measured share times 0.821, and each adult band the measured share times 1.115. Every band keeps its measured ratio to the others in its group, so the generator, which reads these shares as weights, draws almost exactly the same ages as before." },
     { "path": "groups.smallGroups.pctDidAttend", "value": 65, "reason": "Design choice. Small group attendance sits between the measured rate and a livelier demo church (docs/small-groups.md)." },
     { "path": "groups.smallGroups.weightedMedianSize", "value": 12, "reason": "Design choice. Small groups have about 12 members (decision 33)." },
     { "path": "groups.smallGroups.pctLeaders", "value": 8.3, "reason": "Design choice. Each small group has one leader, about 1 in 12 members (decision 33)." },

docs/crowd.md

@@ -9,6 +9,8 @@ The Cast is hand-designed. Everyone else is generated: the **Crowd** gives Full
 3. Names come from public-domain frequency data and never depend on photo ethnicity.
 4. Crowd households have no photos. About half of Core 3's companions get photos from the pool (see [Datasets](../datasets/README.md)).
 5. Core 3's companions use a more involved connection status mix than the Crowd, set in the dataset manifest, so more of them attend, give, and join groups (decision 142). Core 1 and Core 3 also scale up checks as a payment method, so check batches and check images have enough to show (decision 143).
+6. Every generated person has a birth date. Measured age mixes count only people with a birth date, so the profile states the age mix as shares of all people, and validation grades it against people with a birth date, which is nearly all of them (decision 156).
+7. A child on their own, in a one-person family, is a student aged 12 to 17 (decision 157).
 
 ## How big the Crowd is