docs(changelog): make the first release v0.1.0, and fold in the alpha section - #223
Merged
kuny0707 merged 2 commits intoAug 22, 2026
Merged
Conversation
… section The changelog described a `0.1.0-alpha` release that never happened. There are no tags in this repository and no published releases, so that heading documented a version nobody could install, and its two link references at the bottom (`compare/v0.1.0-alpha...HEAD`, `releases/tag/v0.1.0-alpha`) were dead. It also appeared twice in a row until recently. Everything is therefore one release. `[Unreleased]` and `[0.1.0-alpha]` are merged into a single `## [0.1.0]`, with the Added list split into **Foundation** (what the alpha section described: the CLI, the intent schema, the render and SSH work) and **Since** (everything after). Changed / Fixed / Security / Repository changes carry over unchanged. Content is preserved line-for-line apart from the two intro paragraphs, which are rewritten into one; a diff of every non-heading line confirms 356 of 358 lines are identical and the 2 differences are those intros. `0.1.0` rather than `0.1.0-alpha`: goreleaser runs with `prerelease: auto`, so a tag carrying a pre-release suffix is filed as a pre-release, and `/releases/latest` — which `scripts/install.sh` queries and the README one-liner depends on — does not return pre-releases. The suffix would have cost a working install path to restate something `0.x` already says under semver. `0.1.0` rather than `1.0.0`: the public surface is not only the CLI flags. It is `schemas/intent.schema.json`, the ~30 schemas under `schemas/output/`, and the exit-code contract `AGENTS.md` instructs agents to branch on. The constitution requires strict semver, so `1.0.0` freezes all of that behind a major-bump promise before any of it has met a real user. `TODOS.md` still carries four deferred decisions, one of them an unreconciled overlap between `scripts/db_cp.sh` and `trond snapshot clone`. The date is left as `2026-XX-XX` because releases are cut by hand and the date is not known until someone dispatches the workflow. To stop that placeholder from shipping, release.yml now checks, before it builds anything, that the top released section names the tag being released and ends in a real date. Both failure modes were exercised locally: the file's current state is rejected for the placeholder, `v0.2.0` against a `[0.1.0]` heading is rejected for the version mismatch, and a filled-in date is accepted. Stacked on tronprotocol#222 — that PR's commits are included here and the diff shrinks to CHANGELOG.md plus the guard step once it merges.
T091 is an unchecked task instructing whoever runs it to tag `v0.1.0-alpha`, which is now the wrong tag. The phased plan below it (v0.1.0-alpha -> v0.2.0-alpha -> v0.3.0-alpha, one per user story) is left as written: it is a record of what was planned, not an instruction, and it was not followed.
barbatos2011
force-pushed
the
chore/changelog-v0.1.0
branch
from
August 22, 2026 11:51
d38f166 to
457f9fe
Compare
barbatos2011
added a commit
to barbatos2011/tron-deployment
that referenced
this pull request
Aug 23, 2026
Self-review of the audit turned up two things I got wrong. The partial-success guidance I added to AGENTS.md was itself inaccurate, in the direction that matters most: it told agents "re-running the whole command is usually wrong: the nodes that succeeded are already in the requested state." Only one command emits PARTIAL_SUCCESS — `network destroy` — and for that one the reasoning is backwards. Its message is `state cleaned up regardless`: trond has already dropped every node from state, so a retry returns NETWORK_NOT_FOUND, and the entries in `failed` are containers or units still running on the target with nothing tracking them. The advice is now "do not retry, surface the `failed` list for manual cleanup", plus what the other multi-node commands actually do instead (`network create` stops at the first failure with DEPLOY_ERROR, `network upgrade` with UPGRADE_FAILED). The same over-generalisation is corrected in exitcode.go and cli-contract.md. The CHANGELOG restructure put the 40-command enumeration under **Foundation** — the subsection tronprotocol#223 created to mean "what the never-published alpha described". It listed the entire v0.1.0 surface, including recipe, schema, mcp, doctor, verify-config, build and shadow-fork, all of which are itemised again below under **Since**. Release notes that say "Foundation: everything" then "Since: some of that again" are worse than the wrong count they replaced. The total is now a lead paragraph under `### Added`, where it describes the release; Foundation goes back to naming the command groups the project launched with. Also checked while reviewing, no change needed: only the root command defines PersistentPreRunE, so nothing shadows the new validation or paths.SetBaseDir; SchemaVersion governs the output-JSON schemas, not the CLI flag surface, so removing --config needs no bump; `shadow-fork mutate --config` binds its own local flag and still works — in fact removing the root persistent --config takes away a latent shadowing hazard between the two. make test 25/25; gofmt and go vet clean; knowledge/ and internal/knowledge/files/ still byte-identical.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The problem
The changelog described a
0.1.0-alpharelease that never happened. There are no tags in this repository and no published releases:So that heading documented a version nobody could install, and both link references at the bottom —
compare/v0.1.0-alpha...HEADandreleases/tag/v0.1.0-alpha— were dead. It also appeared twice in a row until #222 fixed that.The change
Everything is one release.
[Unreleased]and[0.1.0-alpha]merge into a single## [0.1.0], and the### Addedlist is split into Foundation (what the alpha section described — the CLI, the intent schema, render, SSH) and Since (everything after).Changed/Fixed/Security/Repository changescarry over unchanged. A fresh empty## [Unreleased]sits on top, per Keep a Changelog.Content is preserved line for line apart from the two intro paragraphs, which become one. Verified rather than eyeballed — comparing every non-heading, non-blank, non-linkref line before and after:
Why
0.1.0and not0.1.0-alphagoreleaser runs with
prerelease: auto, so a tag carrying a pre-release suffix is filed as a pre-release — and/releases/latest, whichscripts/install.shqueries and the README one-liner depends on, does not return pre-releases. The suffix would cost a working install path in order to restate something0.xalready says under semver.Why
0.1.0and not1.0.0The public surface here is not only the CLI flags. It is
schemas/intent.schema.json(~50 fields), the ~30 machine-readable schemas underschemas/output/, and the exit-code contract thatAGENTS.mdtells agents to branch on. The constitution requires strict semver, so1.0.0would freeze all of that behind a major-bump promise before any of it has met a real user.TODOS.mdalso still carries four deferred decisions, one an unreconciled overlap betweenscripts/db_cp.shandtrond snapshot clone.0.2.0,0.3.0and so on from here;1.0.0when those schemas have been through real use and the project is willing to back them.The date placeholder, and a guard for it
The date stays
2026-XX-XXbecause releases are cut by hand (#222) and the date is not known until someone dispatches the workflow. That is an easy thing to ship unfilled and invisible afterwards, sorelease.ymlnow checks — before it builds anything — that the top released section names the tag being released and ends in a real date.Both failure modes were exercised locally:
Dispatch on the tag so
GITHUB_REF_NAMEis the tag:gh workflow run release.yml --ref v0.1.0.Also
specs/001-trond-cli-platform/tasks.mdT091 is an open, unchecked task telling whoever runs it to tagv0.1.0-alpha. Repointed atv0.1.0. The phased plan below it (v0.1.0-alpha→v0.2.0-alpha→v0.3.0-alpha, one per user story) is deliberately left as written — it records what was planned, and it was not followed; everything landed on develop untagged.Not in this PR
Filling in the release date. That happens when someone decides to tag, and the guard above will refuse the release until they do.