From 7946fc43318c5c8f79bcd5c51ee4f7b59ec5360a Mon Sep 17 00:00:00 2001 From: barbatos2011 <162298485+barbatos2011@users.noreply.github.com> Date: Sat, 22 Aug 2026 16:37:38 +0800 Subject: [PATCH 1/2] docs(changelog): make the first release v0.1.0, and fold in the alpha section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 #222 — that PR's commits are included here and the diff shrinks to CHANGELOG.md plus the guard step once it merges. --- .github/workflows/release.yml | 18 +++++++ CHANGELOG.md | 92 +++++++++++++++++++++-------------- 2 files changed, 73 insertions(+), 37 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a01e6e02..7cc368c9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -31,6 +31,24 @@ jobs: with: go-version: "1.25" + # The top released section of the changelog must name the tag being + # released and carry a real date. Between releases that heading sits at + # `## [0.1.0] - 2026-XX-XX`; shipping the placeholder is easy to do and + # invisible once the release is out. Dispatch this workflow on the tag + # (`gh workflow run release.yml --ref v0.1.0`) so GITHUB_REF_NAME is it. + - name: CHANGELOG matches the tag + run: | + tag="${GITHUB_REF_NAME#v}" + line=$(grep -m1 -E '^## \[[0-9]' CHANGELOG.md) + echo "releasing: $GITHUB_REF_NAME" + echo "changelog: $line" + case "$line" in + *"[$tag]"*) ;; + *) echo "::error::top changelog version is not [$tag]"; exit 1 ;; + esac + echo "$line" | grep -qE '[0-9]{4}-[0-9]{2}-[0-9]{2}[[:space:]]*$' \ + || { echo "::error::changelog date is still a placeholder"; exit 1; } + - name: Run tests run: make test diff --git a/CHANGELOG.md b/CHANGELOG.md index 148b1310..57336efb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -The agent-ergonomics arc lands across four sequenced PRs: +## [0.1.0] — 2026-XX-XX + +First tagged release. The project transitions from a curated set of HOCON +configuration templates into a CLI for declarative TRON node deployment. + +Nothing was published before this tag — no `v0.1.0-alpha` release ever existed, +so the work that was previously filed under that heading is folded in here. + +`0.x` is deliberate. The public surface is not just 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. Those are worth changing in response to real use before +they are frozen behind a compatibility promise, which is what `1.0.0` would +mean under the semantic-versioning rule in the project constitution. + +The agent-ergonomics arc landed across four sequenced PRs: **#151** (CLI core + AGENTS.md) → **#152** (`trond schema`) → **#153** (`trond mcp`) → **#154** (`trond recipe`). ### Added + +**Foundation** + +- 32 CLI commands across lifecycle (apply / stop / start / restart / upgrade / + rollback / remove), configuration (validate / render / diff / docs), + observability (status / list / logs / health / diagnose / verify / inspect / + events), test-harness SDK (exec / files / wait), chaos primitives + (disconnect / connect / partition / heal), private networks (create / add / + status / destroy), environment (preflight / bootstrap), knowledge base, and + meta (version / completion / help) +- Declarative intent.yaml schema covering ~50 fields: + target (local/ssh, runtime, auto_ports), node (type, version, image, ports, + resources, jvm, storage, restart, extra_env, extra_args, labels, networks, + depends_on, healthcheck, ulimits, extra_hosts, entrypoint, logging, + shm_size, jar source URL+SHA256), network_overrides + (seeds, active_peers, p2p_version, discovery, max_connections, …), + witness_key (private_key_env, keystore_path, account_address), + config_overrides (arbitrary HOCON dotted-key escape hatch) +- HOCON two-pass render: in-place key rewrites + appended override block +- Compose render aligned with the official `tronprotocol/java-tron` image: + `/java-tron/conf`, `/java-tron/output-directory`, `/java-tron/logs` +- SSH host-key verification with explicit MITM detection (TOFU opt-in via + `TROND_SSH_ACCEPT_NEW_HOSTS=1`) +- SSH command whitelist enforced at `Exec` entry +- Private key never written to env or stdout — `PrivateKey` type redacted in + every formatter; witness key inlined into HOCON (which is 0600 on disk) +- `--state-dir` / `TROND_STATE_DIR` for parallel test enclaves +- `target.auto_ports: true` allocates free TCP+UDP ports automatically +- `network create` auto-wires `node.active` peering between siblings +- Audit log (JSONL) for every mutating command, streamable via `events --follow` + +**Since** + - **`jvm.extra_opts`** — an escape hatch for JVM flags outside the closed heap/GC field set, appended last so they win on any last-flag-wins option. Needed because trond runs the JAR directly and so never reads @@ -187,6 +235,7 @@ The agent-ergonomics arc lands across four sequenced PRs: - `scripts/install.sh` — single-shot installer with SHA256 verification ### Changed + - `goreleaser` now produces .deb / .rpm / .apk packages alongside the tar.gz archives; release notes group commits by feat/fix - CI matrix expanded: `lint`, `test+coverage`, `govulncheck`, and @@ -206,6 +255,7 @@ The agent-ergonomics arc lands across four sequenced PRs: (was a documented TODO before); refuses `/` and empty paths ### Fixed + - **`config_overrides` rendered Go syntax, not HOCON.** `hoconValue` fell back to `fmt.%v` for slices and maps, emitting `[map[address:T… voteCount:5000]]` — which no HOCON parser accepts — so every list-valued override was @@ -261,6 +311,7 @@ The agent-ergonomics arc lands across four sequenced PRs: the SSH key after apply) ### Security + - **GitHub Releases is the only publication channel.** The Homebrew tap and the `tronprotocol/trond` Docker image were configured and are removed before the first tag. Both needed a long-lived credential in this @@ -336,41 +387,8 @@ The agent-ergonomics arc lands across four sequenced PRs: `monitoring.grafana.admin_password_env` (the NAME of an env var feeding `GF_SECURITY_ADMIN_PASSWORD`) -## [0.1.0-alpha] — 2026-XX-XX - -Initial public alpha. The project transitions from a curated set of HOCON -configuration templates into a CLI for declarative TRON node deployment. - -### Added -- 32 CLI commands across lifecycle (apply / stop / start / restart / upgrade / - rollback / remove), configuration (validate / render / diff / docs), - observability (status / list / logs / health / diagnose / verify / inspect / - events), test-harness SDK (exec / files / wait), chaos primitives - (disconnect / connect / partition / heal), private networks (create / add / - status / destroy), environment (preflight / bootstrap), knowledge base, and - meta (version / completion / help) -- Declarative intent.yaml schema covering ~50 fields: - target (local/ssh, runtime, auto_ports), node (type, version, image, ports, - resources, jvm, storage, restart, extra_env, extra_args, labels, networks, - depends_on, healthcheck, ulimits, extra_hosts, entrypoint, logging, - shm_size, jar source URL+SHA256), network_overrides - (seeds, active_peers, p2p_version, discovery, max_connections, …), - witness_key (private_key_env, keystore_path, account_address), - config_overrides (arbitrary HOCON dotted-key escape hatch) -- HOCON two-pass render: in-place key rewrites + appended override block -- Compose render aligned with the official `tronprotocol/java-tron` image: - `/java-tron/conf`, `/java-tron/output-directory`, `/java-tron/logs` -- SSH host-key verification with explicit MITM detection (TOFU opt-in via - `TROND_SSH_ACCEPT_NEW_HOSTS=1`) -- SSH command whitelist enforced at `Exec` entry -- Private key never written to env or stdout — `PrivateKey` type redacted in - every formatter; witness key inlined into HOCON (which is 0600 on disk) -- `--state-dir` / `TROND_STATE_DIR` for parallel test enclaves -- `target.auto_ports: true` allocates free TCP+UDP ports automatically -- `network create` auto-wires `node.active` peering between siblings -- Audit log (JSONL) for every mutating command, streamable via `events --follow` - ### Repository changes + - HOCON templates remain at the repository root (`main_net_config.conf`, `test_net_config.conf`, `private_net_config.conf`) and continue to track upstream. `make sync-templates` refreshes them @@ -378,5 +396,5 @@ configuration templates into a CLI for declarative TRON node deployment. release time and bundled into the binary so `trond config render` works from any working directory -[Unreleased]: https://github.com/tronprotocol/tron-deployment/compare/v0.1.0-alpha...HEAD -[0.1.0-alpha]: https://github.com/tronprotocol/tron-deployment/releases/tag/v0.1.0-alpha +[Unreleased]: https://github.com/tronprotocol/tron-deployment/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/tronprotocol/tron-deployment/releases/tag/v0.1.0 From 457f9fe287fc2047069b43886577f975aed91f1d Mon Sep 17 00:00:00 2001 From: barbatos2011 <162298485+barbatos2011@users.noreply.github.com> Date: Sat, 22 Aug 2026 16:38:10 +0800 Subject: [PATCH 2/2] docs(spec): point the open release task at v0.1.0 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. --- specs/001-trond-cli-platform/tasks.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specs/001-trond-cli-platform/tasks.md b/specs/001-trond-cli-platform/tasks.md index 21262585..ecb2321d 100644 --- a/specs/001-trond-cli-platform/tasks.md +++ b/specs/001-trond-cli-platform/tasks.md @@ -231,7 +231,11 @@ - [ ] T088 Run golangci-lint on entire codebase and fix all findings - [ ] T089 Run `trond config validate` against all example intent files to verify they pass - [ ] T090 Validate quickstart.md scenarios end-to-end -- [ ] T091 Tag v0.1.0-alpha release and verify goreleaser + cosign pipeline +- [ ] T091 Tag v0.1.0 release and verify goreleaser + cosign pipeline + (was `v0.1.0-alpha`; the phased alpha plan further down was never + followed — everything landed on develop untagged and ships as one + `v0.1.0`. `prerelease: auto` would also file any `-alpha` tag as a + pre-release, which `scripts/install.sh` does not resolve.) ---