Skip to content

docs(changelog): make the first release v0.1.0, and fold in the alpha section - #223

Merged
kuny0707 merged 2 commits into
tronprotocol:developfrom
barbatos2011:chore/changelog-v0.1.0
Aug 22, 2026
Merged

docs(changelog): make the first release v0.1.0, and fold in the alpha section#223
kuny0707 merged 2 commits into
tronprotocol:developfrom
barbatos2011:chore/changelog-v0.1.0

Conversation

@barbatos2011

@barbatos2011 barbatos2011 commented Aug 22, 2026

Copy link
Copy Markdown

Was stacked on #222. That merged as 235ff82, so this branch is rebased onto develop and now carries only its own two commits — CHANGELOG.md, one step in release.yml, and one line in specs/.

The problem

The changelog described a 0.1.0-alpha release that never happened. There are no tags in this repository and no published releases:

$ git tag                                          # (empty)
$ gh release list -R tronprotocol/tron-deployment  # (empty)

So that heading documented a version nobody could install, and both link references at the bottom — compare/v0.1.0-alpha...HEAD and releases/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 ### Added list is split into Foundation (what the alpha section described — the CLI, the intent schema, render, SSH) and Since (everything after). Changed / Fixed / Security / Repository changes carry 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:

old content lines: 358   new: 368
LOST from old (2):
  - The agent-ergonomics arc lands across four sequenced PRs:
  - Initial public alpha. The project transitions from a curated set of HOCON
ADDED in new (12):   # the rewritten intro, plus **Foundation** / **Since**

Why 0.1.0 and not 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 cost a working install path in order to restate something 0.x already says under semver.

Why 0.1.0 and not 1.0.0

The public surface here is not only the CLI flags. It is schemas/intent.schema.json (~50 fields), the ~30 machine-readable schemas under schemas/output/, and the exit-code contract that AGENTS.md tells agents to branch on. The constitution requires strict semver, so 1.0.0 would freeze all of that behind a major-bump promise before any of it has met a real user. TODOS.md also still carries four deferred decisions, one an unreconciled overlap between scripts/db_cp.sh and trond snapshot clone.

0.2.0, 0.3.0 and so on from here; 1.0.0 when 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-XX because 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, so 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:

REJECT (placeholder date):  v0.1.0 / '## [0.1.0] — 2026-XX-XX'   ← the file's current state
ACCEPT:                     v0.1.0 / '## [0.1.0] — 2026-09-01'
REJECT (version mismatch):  v0.2.0 / '## [0.1.0] — 2026-09-01'

Dispatch on the tag so GITHUB_REF_NAME is the tag: gh workflow run release.yml --ref v0.1.0.

Also

specs/001-trond-cli-platform/tasks.md T091 is an open, unchecked task telling whoever runs it to tag v0.1.0-alpha. Repointed at v0.1.0. The phased plan below it (v0.1.0-alphav0.2.0-alphav0.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.

… 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
barbatos2011 force-pushed the chore/changelog-v0.1.0 branch from d38f166 to 457f9fe Compare August 22, 2026 11:51
@kuny0707
kuny0707 merged commit 4d69296 into tronprotocol:develop Aug 22, 2026
10 checks passed
@barbatos2011
barbatos2011 deleted the chore/changelog-v0.1.0 branch August 22, 2026 11:56
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants