|
| 1 | +--- |
| 2 | +name: upgrade-changelog |
| 3 | +description: "Generates CHANGELOG.md entries for upgrade versions found in upgrades/software/ by parsing init.go and upgrade.go" |
| 4 | +--- |
| 5 | +# Instructions |
| 6 | + |
| 7 | +Generate changelog entries in `upgrades/CHANGELOG.md` for any upgrade version under `upgrades/software/` that doesn't already have an entry. |
| 8 | + |
| 9 | +## Steps |
| 10 | + |
| 11 | +1. **Find semver directories** — list all directories under `upgrades/software/` whose names match `v<major>.<minor>.<patch>` (e.g., `v2.0.0`, `v1.0.0`). |
| 12 | + |
| 13 | +2. **Read `upgrades/CHANGELOG.md`** — identify which versions already have entries by scanning for `##### vX.Y.Z` headings. If a version already has a heading, skip it entirely. |
| 14 | + |
| 15 | +3. **For each new version** (no existing heading), gather data from two files: |
| 16 | + |
| 17 | + ### 3a. Parse `upgrades/software/<version>/init.go` |
| 18 | + |
| 19 | + Find all `utypes.RegisterMigration(...)` calls. Each call has the form: |
| 20 | + ```go |
| 21 | + utypes.RegisterMigration(moduleName, version, handlerFn) |
| 22 | + ``` |
| 23 | + - `moduleName` is a Go constant (e.g., `dv1.ModuleName`). Resolve it: |
| 24 | + 1. Find the import alias (e.g., `dv1 "pkg.akt.dev/go/node/deployment/v1"`) |
| 25 | + 2. Search the imported package for `ModuleName` constant definition to get the actual string value |
| 26 | + - `version` is a `uint64` — this is the **from** version. The **to** version is `version + 1`. |
| 27 | + - Record each migration as: `moduleName version -> version+1` |
| 28 | + |
| 29 | + ### 3b. Parse `upgrades/software/<version>/upgrade.go` |
| 30 | + |
| 31 | + Find the `StoreLoader()` method. It returns a `*storetypes.StoreUpgrades` struct with optional fields: |
| 32 | + - `Added: []string{...}` — new stores |
| 33 | + - `Renamed: []storetypes.StoreRename{...}` — renamed stores |
| 34 | + - `Deleted: []string{...}` — removed stores |
| 35 | + |
| 36 | + If `StoreLoader()` returns `nil`, there are no store changes. |
| 37 | + |
| 38 | + For each store key constant (e.g., `epochstypes.StoreKey`, `ttypes.ModuleName`): |
| 39 | + 1. Find the import alias in the file |
| 40 | + 2. Search the imported package for the constant definition to get the actual string value |
| 41 | + |
| 42 | +4. **Insert the new entry** in `upgrades/CHANGELOG.md` immediately after the line: |
| 43 | + ``` |
| 44 | + Add new upgrades after this line based on the template above |
| 45 | + ``` |
| 46 | + followed by `-----`. |
| 47 | + |
| 48 | + Use this format (newest entries go first, right after the delimiter): |
| 49 | + |
| 50 | + ```markdown |
| 51 | + |
| 52 | + ##### vX.Y.Z |
| 53 | + |
| 54 | + ###### Description |
| 55 | + |
| 56 | + - Stores |
| 57 | + - added |
| 58 | + - `storeName`: brief description if available |
| 59 | + - renamed |
| 60 | + - `oldName` -> `newName` |
| 61 | + - deleted |
| 62 | + - `storeName`: brief description if available |
| 63 | + |
| 64 | + - Migrations |
| 65 | + - moduleName `from -> to` |
| 66 | + ``` |
| 67 | + |
| 68 | + **Omission rules** (match existing CHANGELOG style): |
| 69 | + - Omit the entire `Stores` section if there are no added, renamed, or deleted stores |
| 70 | + - Omit `added`/`renamed`/`deleted` subsections individually if empty |
| 71 | + - Omit the entire `Migrations` section if there are no migrations |
| 72 | + - Always include the `###### Description` heading (leave it for the user to fill in) |
| 73 | + |
| 74 | +5. **Report results** — list each version processed and what was added. For skipped versions (already in CHANGELOG), mention they were skipped. |
| 75 | + |
| 76 | +## Important notes |
| 77 | + |
| 78 | +- Store key constants may be named `StoreKey` or `ModuleName` — both are used as store identifiers. Resolve whichever constant appears in the code. |
| 79 | +- When resolving Go constants from external packages, search under the Go module cache or use `go doc` if needed. The packages typically follow the pattern `pkg.akt.dev/go/node/<module>/<version>`. |
| 80 | +- If a constant cannot be resolved, use the raw Go expression as a placeholder (e.g., `` `epochstypes.StoreKey` ``) and warn the user. |
| 81 | +- Multiple versions may need entries — process them all in one run, inserting newest first after the delimiter. |
0 commit comments