|
| 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 |
0 commit comments