Skip to content

Commit 00aa5d3

Browse files
celialaceliala
committed
clusterversion: sync documentation from release-25.4
The release-25.4 branch has enhanced documentation for release preparation processes, including a new CLAUDE.md file with detailed runbooks and updated README.md with Claude prompt examples. This change brings those documentation improvements to master: - Adds CLAUDE.md with step-by-step instructions for R.1 (beta prep) and R.2 (minting releases) - Updates README.md with Claude prompt examples for R.1 and R.2 - Updates R.1 example PR reference to a more recent example (#153906) These additions provide clearer guidance for future release processes and make the runbooks more accessible for AI-assisted workflows. Release Notes: None Epic: None
1 parent 1a4ff79 commit 00aa5d3

File tree

2 files changed

+222
-1
lines changed

2 files changed

+222
-1
lines changed

‎pkg/clusterversion/CLAUDE.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# CockroachDB Release Preparation Guide
2+
3+
This document provides step-by-step instructions for preparing the CockroachDB source tree for beta releases, specifically following the R.1: Prepare for beta checklist from the clusterversion README.md.
4+
5+
## Beta Release Preparation (R.1 Checklist)
6+
7+
When preparing for a beta release (e.g., 25.4 beta1), the following files must be updated:
8+
9+
### 1. Core Version Changes
10+
11+
**Set Development Branch Flag:**
12+
- File: `pkg/clusterversion/cockroach_versions.go`
13+
- Change: Set `const DevelopmentBranch = false` (line ~334)
14+
15+
**Update Version String:**
16+
- File: `pkg/build/version.txt`
17+
- Change: Update from alpha to beta version (e.g., `v25.4.0-alpha.2` → `v25.4.0-beta.1`)
18+
19+
### 2. Regenerate Documentation
20+
21+
Run the following command to update generated documentation:
22+
```bash
23+
./dev gen docs
24+
```
25+
26+
This updates:
27+
- `docs/generated/settings/settings-for-tenants.txt`
28+
- `docs/generated/settings/settings.html`
29+
30+
### 3. Update Test Data
31+
32+
**System Schema Tests:**
33+
Run this command to regenerate bootstrap test data:
34+
```bash
35+
./dev test pkg/sql/catalog/systemschema_test --rewrite
36+
```
37+
38+
This updates:
39+
- `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
40+
- `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
41+
42+
**Bootstrap Hash Test:**
43+
Run this command and manually update hash values if the test fails:
44+
```bash
45+
./dev test pkg/sql/catalog/bootstrap --rewrite -f TestInitialValuesToString
46+
```
47+
48+
If the rewrite fails, manually update the hash values in:
49+
- `pkg/sql/catalog/bootstrap/testdata/testdata`
50+
- Update `system hash=` value
51+
- Update `tenant hash=` value
52+
- Update binary data values as shown in test output
53+
54+
### 4. CLI Test Data Updates
55+
56+
**Declarative Rules Tests:**
57+
- File: `pkg/cli/testdata/declarative-rules/deprules`
58+
- Change: Update version reference to current release branch (e.g., `debug declarative-print-rules 25.2 dep` → `debug declarative-print-rules 25.3 dep`)
59+
60+
- File: `pkg/cli/testdata/declarative-rules/invalid_version`
61+
- Change: Update supported versions list to reflect current releases (use short format like `25.2`, `25.3` not `1000025.x`)
62+
63+
### 5. Logic Test Updates
64+
65+
**Internal Catalog Test:**
66+
- File: `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog`
67+
- Change: Update `majorVal` from `1000025` to `25` in systemDatabaseSchemaVersion entries
68+
69+
## Example PR Reference
70+
71+
For reference, see PR #148382 which demonstrates the complete set of changes needed for beta release preparation.
72+
73+
## Expected File Count
74+
75+
A typical beta release preparation should modify approximately 10-12 files:
76+
1. `pkg/clusterversion/cockroach_versions.go`
77+
2. `pkg/build/version.txt`
78+
3. `docs/generated/settings/settings-for-tenants.txt`
79+
4. `docs/generated/settings/settings.html`
80+
5. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
81+
6. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
82+
7. `pkg/sql/catalog/bootstrap/testdata/testdata`
83+
8. `pkg/cli/testdata/declarative-rules/deprules`
84+
9. `pkg/cli/testdata/declarative-rules/invalid_version`
85+
10. `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog`
86+
87+
## Verification
88+
89+
After making all changes:
90+
1. Run the bootstrap test to ensure it passes: `./dev test pkg/sql/catalog/bootstrap -f TestInitialValuesToString`
91+
2. Check git status to verify expected number of modified files
92+
3. All tests should pass before proceeding with the release
93+
94+
## Notes
95+
96+
- Some test data files contain binary encoded data that may change when version numbers are updated
97+
- Hash values in bootstrap test data are expected to change when the development branch flag is modified
98+
- The logic test updates are necessary to reflect the new major version in system database schema version metadata
99+
- CLI declarative rules tests use short version format (e.g., `25.3`) not the long format (e.g., `1000025.3`)
100+
- Always run the CLI tests after updating declarative rules files to ensure correct version format
101+
102+
---
103+
104+
## R.2: Mint Release (Creating Final Version)
105+
106+
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).
107+
108+
**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.
109+
110+
### Critical Step: Update SystemDatabaseSchemaBootstrapVersion
111+
112+
**IMPORTANT:** This is the most commonly missed step and will cause test failures if forgotten.
113+
114+
**File:** `pkg/sql/catalog/systemschema/system.go` (line ~1445)
115+
116+
**Change:** Update from the last internal version to the final minted version:
117+
118+
```go
119+
// Before (last internal version - e.g., V25_4_AddSystemStatementHintsTable)
120+
var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4_AddSystemStatementHintsTable.Version()
121+
122+
// After (final minted version - e.g., V25_4)
123+
var SystemDatabaseSchemaBootstrapVersion = clusterversion.V25_4.Version()
124+
```
125+
126+
### Full Checklist
127+
128+
1. **Update cockroach_versions.go:**
129+
- Add the final version key (e.g., `V25_4`) with `Internal: 0`
130+
- Set `finalVersion` constant to this key (e.g., `const finalVersion Key = V25_4`)
131+
132+
2. **Update SystemDatabaseSchemaBootstrapVersion** (see above - critical!)
133+
134+
3. **Update version.txt:**
135+
```bash
136+
# Update pkg/build/version.txt to RC version (e.g., v25.4.0-rc.1)
137+
# Note: Minting happens before the final release, typically when cutting rc.1
138+
```
139+
140+
4. **Regenerate documentation:**
141+
```bash
142+
./dev gen docs
143+
```
144+
145+
5. **Regenerate bootstrap test data:**
146+
```bash
147+
./dev test pkg/sql/catalog/systemschema_test --rewrite
148+
```
149+
This updates:
150+
- `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
151+
- `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
152+
153+
6. **Update bootstrap hash test data:**
154+
155+
Run the test to see what values need updating:
156+
```bash
157+
./dev test pkg/sql/catalog/bootstrap -f TestInitialValuesToString
158+
```
159+
160+
The test will fail showing the expected hash values. Update in `pkg/sql/catalog/bootstrap/testdata/testdata`:
161+
- Line 1: `system hash=<new_hash_from_test_output>`
162+
- Line ~228: `tenant hash=<new_hash_from_test_output>`
163+
- Update the binary data on the line following each hash (the `{"key":"8b89898a89","value":"..."}` entry)
164+
165+
7. **Update logic test data:**
166+
167+
After updating `SystemDatabaseSchemaBootstrapVersion`, you need to update the expected test output:
168+
169+
- File: `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog`
170+
- Change: Update the `systemDatabaseSchemaVersion` in the test data to match the new minted version
171+
172+
**Before (with internal version):**
173+
```
174+
1 {"database": {"id": 1, "name": "system", ... "systemDatabaseSchemaVersion": {"internal": 14, "majorVal": 25, "minorVal": 3}, ...}}
175+
```
176+
177+
**After (final minted version):**
178+
```
179+
1 {"database": {"id": 1, "name": "system", ... "systemDatabaseSchemaVersion": {"majorVal": 25, "minorVal": 4}, ...}}
180+
```
181+
182+
Note: The `internal` field should be removed when minting the final version.
183+
184+
8. **Verify all tests pass:**
185+
```bash
186+
./dev test pkg/sql/catalog/bootstrap -f TestInitialValuesToString
187+
./dev test pkg/sql/catalog/systemschema_test
188+
./dev test pkg/sql/logictest -f crdb_internal_catalog
189+
```
190+
191+
### Common Errors and Solutions
192+
193+
**Error: "Unexpected hash value for system"**
194+
- **Cause:** Forgot to update `SystemDatabaseSchemaBootstrapVersion` in step 2
195+
- **Fix:** Complete step 2, then re-run steps 5-7
196+
197+
**Error: "output didn't match expected" with binary data diff**
198+
- **Cause:** The binary-encoded system database descriptor needs updating
199+
- **Fix:** Copy the exact binary value from the test output diff (shown after the `+` sign) and paste it into the testdata file
200+
201+
### Expected Files Modified
202+
203+
A typical R.2 mint should modify:
204+
1. `pkg/clusterversion/cockroach_versions.go` (add final version, set finalVersion)
205+
2. `pkg/sql/catalog/systemschema/system.go` (update SystemDatabaseSchemaBootstrapVersion)
206+
3. `pkg/build/version.txt` (update to final version)
207+
4. `docs/generated/settings/settings-for-tenants.txt`
208+
5. `docs/generated/settings/settings.html`
209+
6. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_system`
210+
7. `pkg/sql/catalog/systemschema_test/testdata/bootstrap_tenant`
211+
8. `pkg/sql/catalog/bootstrap/testdata/testdata` (hashes and binary data)
212+
9. `pkg/sql/logictest/testdata/logic_test/crdb_internal_catalog` (update systemDatabaseSchemaVersion)
213+
214+
### Example PRs
215+
216+
- For reference: [#112347](https://github.com/cockroachdb/cockroach/pull/112347)
217+
- 25.3 mint: [#150211](https://github.com/cockroachdb/cockroach/pull/150211)

‎pkg/clusterversion/README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,13 +97,15 @@ code for more details.
9797

9898
**When**: When we are ready to select the first beta candidate.
9999

100+
**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"
101+
100102
**Checklist**:
101103
- [ ] Set `developmentBranch` constant to `false`
102104
- [ ] Update `version.txt` to the beta version, e.g. `24.1.0-beta.1`
103105
- [ ] Regenerate docs (`./dev gen docs`)
104106
- [ ] Regenerate expected test data results as needed
105107

106-
**Example PR:** [#113912](https://github.com/cockroachdb/cockroach/pull/113912)
108+
**Example PR:** [#153906](https://github.com/cockroachdb/cockroach/pull/153906)
107109

108110
### R.2: Mint release
109111

@@ -112,6 +114,8 @@ code for more details.
112114
**When**: When we are absolutely sure that we no longer need additional version
113115
gates - right before the final RC at the latest.
114116

117+
**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."
118+
115119
**Checklist**:
116120
- [ ] Replace temporary constant for current release (e.g. `V24_1`) with a
117121
cluster version key, associated with a "final" (`Internal=0`) version (e.g.

0 commit comments

Comments
 (0)