Merge pull request #155421 from celiala/release-25.4.mint-25.4

celiala · web-flow · commit 00809c0b1a28 · 2025-10-17T13:14:14.000-04:00
release-25.4: clusterversion: mint 25.4
diff --git a/docs/generated/settings/settings-for-tenants.txt b/docs/generated/settings/settings-for-tenants.txt
@@ -422,4 +422,4 @@ trace.zipkin.collector	string		the address of a Zipkin instance to receive trace
 ui.database_locality_metadata.enabled	boolean	true	if enabled shows extended locality data about databases and tables in DB Console which can be expensive to compute	application
 ui.default_timezone	string		the default timezone used to format timestamps in the ui	application
 ui.display_timezone	enumeration	etc/utc	the timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]	application
-version	version	25.3-upgrading-to-25.4-step-014	set the active cluster version in the format '<major>.<minor>'	application
+version	version	25.4	set the active cluster version in the format '<major>.<minor>'	application
diff --git a/docs/generated/settings/settings.html b/docs/generated/settings/settings.html
@@ -381,6 +381,6 @@
 <tr><td><div id="setting-ui-database-locality-metadata-enabled" class="anchored"><code>ui.database_locality_metadata.enabled</code></div></td><td>boolean</td><td><code>true</code></td><td>if enabled shows extended locality data about databases and tables in DB Console which can be expensive to compute</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 <tr><td><div id="setting-ui-default-timezone" class="anchored"><code>ui.default_timezone</code></div></td><td>string</td><td><code></code></td><td>the default timezone used to format timestamps in the ui</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 <tr><td><div id="setting-ui-display-timezone" class="anchored"><code>ui.display_timezone</code></div></td><td>enumeration</td><td><code>etc/utc</code></td><td>the timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the &#39;ui.default_timezone&#39; setting instead. &#39;ui.default_timezone&#39; takes precedence over this setting. [etc/utc = 0, america/new_york = 1]</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
-<tr><td><div id="setting-version" class="anchored"><code>version</code></div></td><td>version</td><td><code>25.3-upgrading-to-25.4-step-014</code></td><td>set the active cluster version in the format &#39;&lt;major&gt;.&lt;minor&gt;&#39;</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
+<tr><td><div id="setting-version" class="anchored"><code>version</code></div></td><td>version</td><td><code>25.4</code></td><td>set the active cluster version in the format &#39;&lt;major&gt;.&lt;minor&gt;&#39;</td><td>Basic/Standard/Advanced/Self-Hosted</td></tr>
 </tbody>
 </table>
diff --git a/pkg/build/version.txt b/pkg/build/version.txt
@@ -1 +1 @@
-v25.4.0-beta.3
+v25.4.0-rc.1
diff --git a/pkg/clusterversion/CLAUDE.md b/pkg/clusterversion/CLAUDE.md
@@ -97,4 +97,121 @@ After making all changes:
 - Hash values in bootstrap test data are expected to change when the development branch flag is modified
 - The logic test updates are necessary to reflect the new major version in system database schema version metadata
 - CLI declarative rules tests use short version format (e.g., `25.3`) not the long format (e.g., `1000025.3`)
-- Always run the CLI tests after updating declarative rules files to ensure correct version format
+- Always run the CLI tests after updating declarative rules files to ensure correct version format
+
+---
+
+## R.2: Mint Release (Creating Final Version)
+
+This change finalizes the cluster version for the release. It should be done when you are absolutely sure that no additional version gates are needed - right before cutting the first RC (typically rc.1).
+
+**Important timing note:** The minting happens before the final v25.X.0 release. It's typically done when preparing rc.1, which is shipped before the final release.
+
+### Critical Step: Update SystemDatabaseSchemaBootstrapVersion
+
+**IMPORTANT:** This is the most commonly missed step and will cause test failures if forgotten.
+
+**File:** `pkg/sql/catalog/systemschema/system.go` (line ~1445)
+
+**Change:** Update from the last internal version to the final minted version:
+
+```go
+// Before (last internal version - e.g., V25_4_AddSystemStatementHintsTable)
+var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4_AddSystemStatementHintsTable.Version()
+
+// After (final minted version - e.g., V25_4)
+var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4.Version()
+```
+
+### Full Checklist
+
+1. **Update cockroach_versions.go:**
+   - Add the final version key (e.g., `V25_4`) with `Internal: 0`
+   - Set `finalVersion` constant to this key (e.g., `const finalVersion Key = V25_4`)
+
+2. **Update SystemDatabaseSchemaBootstrapVersion** (see above - critical!)
+
+3. **Update version.txt:**
+   ```bash
+   # Update pkg/build/version.txt to RC version (e.g., v25.4.0-rc.1)
+   # Note: Minting happens before the final release, typically when cutting rc.1
+   ```
+
+4. **Regenerate documentation:**
+   ```bash
+   ./dev gen docs
+   ```
+
+5. **Regenerate bootstrap test data:**
+   ```bash
+   ./dev test pkg/sql/catalog/systemschema_test --rewrite
+   ```
+   This updates:
+   - `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
+   - `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
+
+6. **Update bootstrap hash test data:**
+
+   Run the test to see what values need updating:
+   ```bash
+   ./dev test pkg/sql/catalog/bootstrap -f TestInitialValuesToString
+   ```
+
+   The test will fail showing the expected hash values. Update in `pkg/sql/catalog/bootstrap/testdata/testdata`:
+   - Line 1: `system hash=<new_hash_from_test_output>`
+   - Line ~228: `tenant hash=<new_hash_from_test_output>`
+   - Update the binary data on the line following each hash (the `{"key":"8b89898a89","value":"..."}` entry)
+
+7. **Update logic test data:**
+
+   After updating `SystemDatabaseSchemaBootstrapVersion`, you need to update the expected test output:
+
+   - File: `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog`
+   - Change: Update the `systemDatabaseSchemaVersion` in the test data to match the new minted version
+
+   **Before (with internal version):**
+   ```
+   1           {"database": {"id": 1, "name": "system", ... "systemDatabaseSchemaVersion": {"internal": 14, "majorVal": 25, "minorVal": 3}, ...}}
+   ```
+
+   **After (final minted version):**
+   ```
+   1           {"database": {"id": 1, "name": "system", ... "systemDatabaseSchemaVersion": {"majorVal": 25, "minorVal": 4}, ...}}
+   ```
+
+   Note: The `internal` field should be removed when minting the final version.
+
+8. **Verify all tests pass:**
+   ```bash
+   ./dev test pkg/sql/catalog/bootstrap -f TestInitialValuesToString
+   ./dev test pkg/sql/catalog/systemschema_test
+   ./dev test pkg/sql/logictest -f crdb_internal_catalog
+   ```
+
+### Common Errors and Solutions
+
+**Error: "Unexpected hash value for system"**
+- **Cause:** Forgot to update `SystemDatabaseSchemaBootstrapVersion` in step 2
+- **Fix:** Complete step 2, then re-run steps 5-7
+
+**Error: "output didn't match expected" with binary data diff**
+- **Cause:** The binary-encoded system database descriptor needs updating
+- **Fix:** Copy the exact binary value from the test output diff (shown after the `+` sign) and paste it into the testdata file
+
+### Expected Files Modified
+
+A typical R.2 mint should modify:
+1. `pkg/clusterversion/cockroach_versions.go` (add final version, set finalVersion)
+2. `pkg/sql/catalog/systemschema/system.go` (update SystemDatabaseSchemaBootstrapVersion)
+3. `pkg/build/version.txt` (update to final version)
+4. `docs/generated/settings/settings-for-tenants.txt`
+5. `docs/generated/settings/settings.html`
+6. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
+7. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
+8. `pkg/sql/catalog/bootstrap/testdata/testdata` (hashes and binary data)
+9. `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog` (update systemDatabaseSchemaVersion)
+
+### Example PRs
+
+- For reference: [#112347](https://github.com/cockroachdb/cockroach/pull/112347)
+- 25.3 mint: [#150211](https://github.com/cockroachdb/cockroach/pull/150211)
diff --git a/pkg/clusterversion/README.md b/pkg/clusterversion/README.md
@@ -97,6 +97,8 @@ code for more details.
 
 **When**: When we are ready to select the first beta candidate.
 
+**Claude Prompt**: "Please create a PR to prepare the release-25.4 branch for beta.1 following the R.1 checklist in pkg/clusterversion/README.md and the detailed runbook in pkg/clusterversion/CLAUDE.md"
+
 **Checklist**:
  - [ ] Set `developmentBranch` constant to `false`
  - [ ] Update `version.txt` to the beta version, e.g. `24.1.0-beta.1`
@@ -112,6 +114,8 @@ code for more details.
 **When**: When we are absolutely sure that we no longer need additional version
 gates - right before the final RC at the latest.
 
+**Claude Prompt**: "Please create a PR to mint the 25.4 release following the R.2 checklist in pkg/clusterversion/README.md and the detailed runbook in pkg/clusterversion/CLAUDE.md. We're preparing rc.1."
+
 **Checklist**:
 - [ ] Replace temporary constant for current release (e.g. `V24_1`) with a
   cluster version key, associated with a "final" (`Internal=0`) version (e.g.
diff --git a/pkg/clusterversion/cockroach_versions.go b/pkg/clusterversion/cockroach_versions.go
@@ -232,6 +232,9 @@ const (
 	// associated with a query without modifying the query or application itself.
 	V25_4_AddSystemStatementHintsTable
 
+	// V25_4 is CockroachDB v25.4. It's used for all v25.4.x patch releases.
+	V25_4
+
 	// *************************************************
 	// Step (1) Add new versions above this comment.
 	// Do not add new versions to a patch release.
@@ -295,6 +298,8 @@ var versionTable = [numKeys]roachpb.Version{
 
 	V25_4_AddSystemStatementHintsTable: {Major: 25, Minor: 3, Internal: 14},
 
+	V25_4: {Major: 25, Minor: 4, Internal: 0},
+
 	// *************************************************
 	// Step (2): Add new versions above this comment.
 	// Do not add new versions to a patch release.
@@ -312,14 +317,6 @@ const MinSupported Key = V25_2
 // have at least an RC build published).
 const PreviousRelease Key = V25_3
 
-// V25_4 is a placeholder that will eventually be replaced by the actual 25.4
-// version Key, but in the meantime it points to the latest Key. The placeholder
-// is defined so that it can be referenced in code that simply wants to check if
-// a cluster is running 25.4 and has completed all associated migrations; most
-// version gates can use this instead of defining their own version key if they
-// only need to check that the cluster has upgraded to 25.4.
-const V25_4 = Latest
-
 // DevelopmentBranch must be true on the main development branch but should be
 // set to false on a release branch once the set of versions becomes append-only
 // and associated upgrade implementations are frozen.
@@ -337,7 +334,7 @@ const DevelopmentBranch = false
 // version key, e.g. to V23_2 on the release-23.2 branch once it is minted.
 // Setting it has the effect of ensuring no versions are subsequently added (see
 // TestFinalVersion).
-const finalVersion Key = -1
+const finalVersion Key = V25_4
 
 // TestingExtraVersions may be set to true by packages of tests which will
 // intentionally use Keys greater than Latest, which otherwise would crash
diff --git a/pkg/sql/catalog/bootstrap/testdata/testdata b/pkg/sql/catalog/bootstrap/testdata/testdata
@@ -1,7 +1,7 @@
-system hash=fed4e568760c015b3cc9a6bc58492e3239c0bdd6962fb87e9113cf13e5689e38
+system hash=5e65df499c108ed856a729b404c3dc5b92ab9812183543a614c6107bed2f1dcd
 ----
 [{"key":"8b"}
-,{"key":"8b89898a89","value":"0312450a0673797374656d10011a250a0d0a0561646d696e1080101880100a0c0a04726f6f7410801018801012046e6f646518032200280140004a006a08081910031800200e7000"}
+,{"key":"8b89898a89","value":"0312450a0673797374656d10011a250a0d0a0561646d696e1080101880100a0c0a04726f6f7410801018801012046e6f646518032200280140004a006a0808191004180020007000"}
 ,{"key":"8b898b8a89","value":"030aaa030a0a64657363726970746f721803200128013a0042290a02696410011a0e0801104018002a003003501460002000300068007000780080010088010098010042310a0a64657363726970746f7210021a0e0808100018002a0030005011600020013000680070007800800100880100980100480352770a077072696d61727910011801220269642a0a64657363726970746f72300140004a10080010001a00200028003000380040005a0070027a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060026a210a0b0a0561646d696e102018200a0a0a04726f6f741020182012046e6f64651803800101880103980100b201130a077072696d61727910001a02696420012800b201240a1066616d5f325f64657363726970746f7210021a0a64657363726970746f7220022802b80103c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
 ,{"key":"8b898c8a89","value":"030a92070a0575736572731804200128013a00422f0a08757365726e616d6510011a0e0807100018002a003000501960002000300068007000780080010088010098010042350a0e68617368656450617373776f726410021a0e0808100018002a003000501160002001300068007000780080010088010098010042340a066973526f6c6510031a0e0800100018002a0030005010600020002a0566616c73653000680070007800800100880100980100422e0a07757365725f696410041a0e080c100018002a003000501a60002000300068007000780080010088010098010042410a19657374696d617465645f6c6173745f6c6f67696e5f74696d6510051a0f0809100018002a00300050a009600020013000680070007800800100880100980100480652b3010a077072696d617279100118012208757365726e616d652a0e68617368656450617373776f72642a066973526f6c652a07757365725f69642a19657374696d617465645f6c6173745f6c6f67696e5f74696d65300140004a10080010001a00200028003000380040005a0070027003700470057a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00102e00100e9010000000000000000f20100f801005a7a0a1175736572735f757365725f69645f696478100218012207757365725f69643004380140004a10080010001a00200028003000380040005a007a0408002000800100880100900103980100a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060036a250a0d0a0561646d696e10e00318e0030a0c0a04726f6f7410e00318e00312046e6f64651803800101880103980100b201240a077072696d61727910001a08757365726e616d651a07757365725f6964200120042804b2012c0a1466616d5f325f68617368656450617373776f726410021a0e68617368656450617373776f726420022802b2011c0a0c66616d5f335f6973526f6c6510031a066973526f6c6520032803b201420a1f66616d5f355f657374696d617465645f6c6173745f6c6f67696e5f74696d6510051a19657374696d617465645f6c6173745f6c6f67696e5f74696d6520052805b80106c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880303a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
 ,{"key":"8b898d8a89","value":"030a99030a057a6f6e65731805200128013a0042290a02696410011a0e0801104018002a0030035014600020003000680070007800800100880100980100422d0a06636f6e66696710021a0e0808100018002a0030005011600020013000680070007800800100880100980100480352730a077072696d61727910011801220269642a06636f6e666967300140004a10080010001a00200028003000380040005a0070027a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060026a250a0d0a0561646d696e10e00318e0030a0c0a04726f6f7410e00318e00312046e6f64651803800101880103980100b201130a077072696d61727910001a02696420012800b2011c0a0c66616d5f325f636f6e66696710021a06636f6e66696720022802b80103c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
@@ -225,10 +225,10 @@ system hash=fed4e568760c015b3cc9a6bc58492e3239c0bdd6962fb87e9113cf13e5689e38
 ,{"key":"d4"}
 ]
 
-tenant hash=ee07d9bb49e313a136e923f90768a262280a2604f48e920165231b07948b5360
+tenant hash=a76a318582e8c62cd5aa39b169680e55449e96074b62253d2893bd53489140eb
 ----
 [{"key":""}
-,{"key":"8b89898a89","value":"0312450a0673797374656d10011a250a0d0a0561646d696e1080101880100a0c0a04726f6f7410801018801012046e6f646518032200280140004a006a08081910031800200e7000"}
+,{"key":"8b89898a89","value":"0312450a0673797374656d10011a250a0d0a0561646d696e1080101880100a0c0a04726f6f7410801018801012046e6f646518032200280140004a006a0808191004180020007000"}
 ,{"key":"8b898b8a89","value":"030aaa030a0a64657363726970746f721803200128013a0042290a02696410011a0e0801104018002a003003501460002000300068007000780080010088010098010042310a0a64657363726970746f7210021a0e0808100018002a0030005011600020013000680070007800800100880100980100480352770a077072696d61727910011801220269642a0a64657363726970746f72300140004a10080010001a00200028003000380040005a0070027a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060026a210a0b0a0561646d696e102018200a0a0a04726f6f741020182012046e6f64651803800101880103980100b201130a077072696d61727910001a02696420012800b201240a1066616d5f325f64657363726970746f7210021a0a64657363726970746f7220022802b80103c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
 ,{"key":"8b898c8a89","value":"030a92070a0575736572731804200128013a00422f0a08757365726e616d6510011a0e0807100018002a003000501960002000300068007000780080010088010098010042350a0e68617368656450617373776f726410021a0e0808100018002a003000501160002001300068007000780080010088010098010042340a066973526f6c6510031a0e0800100018002a0030005010600020002a0566616c73653000680070007800800100880100980100422e0a07757365725f696410041a0e080c100018002a003000501a60002000300068007000780080010088010098010042410a19657374696d617465645f6c6173745f6c6f67696e5f74696d6510051a0f0809100018002a00300050a009600020013000680070007800800100880100980100480652b3010a077072696d617279100118012208757365726e616d652a0e68617368656450617373776f72642a066973526f6c652a07757365725f69642a19657374696d617465645f6c6173745f6c6f67696e5f74696d65300140004a10080010001a00200028003000380040005a0070027003700470057a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00102e00100e9010000000000000000f20100f801005a7a0a1175736572735f757365725f69645f696478100218012207757365725f69643004380140004a10080010001a00200028003000380040005a007a0408002000800100880100900103980100a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060036a250a0d0a0561646d696e10e00318e0030a0c0a04726f6f7410e00318e00312046e6f64651803800101880103980100b201240a077072696d61727910001a08757365726e616d651a07757365725f6964200120042804b2012c0a1466616d5f325f68617368656450617373776f726410021a0e68617368656450617373776f726420022802b2011c0a0c66616d5f335f6973526f6c6510031a066973526f6c6520032803b201420a1f66616d5f355f657374696d617465645f6c6173745f6c6f67696e5f74696d6510051a19657374696d617465645f6c6173745f6c6f67696e5f74696d6520052805b80106c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880303a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
 ,{"key":"8b898d8a89","value":"030a99030a057a6f6e65731805200128013a0042290a02696410011a0e0801104018002a0030035014600020003000680070007800800100880100980100422d0a06636f6e66696710021a0e0808100018002a0030005011600020013000680070007800800100880100980100480352730a077072696d61727910011801220269642a06636f6e666967300140004a10080010001a00200028003000380040005a0070027a0408002000800100880100900104980101a20106080012001800a80100b20100ba0100c00100c80100d00101e00100e9010000000000000000f20100f8010060026a250a0d0a0561646d696e10e00318e0030a0c0a04726f6f7410e00318e00312046e6f64651803800101880103980100b201130a077072696d61727910001a02696420012800b2011c0a0c66616d5f325f636f6e66696710021a06636f6e66696720022802b80103c20100e80100f2010408001200f801008002009202009a0200b20200b80200c0021dc80200e00200800300880302a80300b00300d00300d80300e00300f80300880400980400a00400a80400b00400"}
diff --git a/pkg/sql/catalog/systemschema/system.go b/pkg/sql/catalog/systemschema/system.go
@@ -1442,7 +1442,7 @@ const SystemDatabaseName = catconstants.SystemDatabaseName
 // release version).
 //
 // NB: Don't set this to clusterversion.Latest; use a specific version instead.
-var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4_AddSystemStatementHintsTable.Version()
+var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4.Version()
 
 // MakeSystemDatabaseDesc constructs a copy of the system database
 // descriptor.
diff --git a/pkg/sql/catalog/systemschema_test/testdata/bootstrap_system b/pkg/sql/catalog/systemschema_test/testdata/bootstrap_system
diff --git a/pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant b/pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant
diff --git a/pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog b/pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog
