Building and Releasing the Tools

Contents

1. Build Trice tool from Go sources

ms@DESKTOP-7POEGPB MINGW64 /c/repos/trice (main)
$ go install ./cmd/trice ./cmd/tlog

This direct local command also builds both tools, using Go’s GOBIN/GOPATH installation directory.

Prefer bash ./scripts/buildTriceTool.sh for metadata and overwrite protection. It includes the current repository state in both binaries, shown by trice version and tlog --version.

2. Prepare A Release

Follow GoReleaser and release-package testing for configuration checks, disposable local snapshots, native package installation and published-release audits. That chapter lists prerequisites and explains what each level proves.

Use this checklist for each selected release. Acceptance checks do not add features or require general documentation changes; a failure needs a focused correction and renewed evidence for the affected checks.

Before creating the tag Required evidence
Candidate Approved commit, intended branch history, clean worktree and recorded commit ID.
Native tests Successful full runs on Linux, macOS and Windows for that candidate; distinguish Intel/Apple Silicon results and any accepted platform limits. Quick PR checks remain useful separate evidence.
CI and coverage Required Actions pass for the candidate; inspect skipped/incomplete jobs and compare coverage with the target-branch baseline using the declared package selection.
Installation and snapshot Both tools, target sources, complete licenses, platform archives, Linux packages and both manual PDFs checked through the existing snapshot/installation jobs.
Notes and known limits The selected version has nonempty English release notes, correct links and an explicit record of accepted deviations.
Relevant manual checks For changed TCP behavior, check Windows for a delayed firewall dialog after process exit. Record RTT hardware checks separately with board, transport and tool versions; compiler tests do not establish hardware operation.
After publication Required evidence
Selected release The expected tag/commit and prerelease/stable status are visible.
Downloads Actual published archives, packages, checksums, target sources and both PDFs are present and usable at their final URLs.
Release audit The manually selected tag passes archive, package-installation and shipped-feature checks. Retain the run URL and any accepted limits.

Local full runs and Actions cover the candidate. The post-publication checks cover the files users actually download. Preserve the distinction when recording results; older successful runs remain evidence for their original revisions.

3. Publish a Release Manually from a Selected Tag

The release workflow runs only when started manually. Publishing a Git tag makes the selected source snapshot available; the separate workflow start publishes its release assets.

3.1. Verify the Candidate Commit

Review the release notes and commit the intended changes. Inspect the remote branches before choosing the candidate:

git fetch origin --tags
git status --short
git branch -vv
git log --oneline --left-right origin/main...origin/wip
git log --oneline -5 HEAD

Confirm which reviewed changes belong in the release and complete their normal branch/PR integration. A tag identifies a commit, not all changes present on another branch. On the chosen clean checkout, record and test the exact candidate:

release_commit=$(git rev-parse HEAD)
printf 'Release candidate: %s\n' "$release_commit"
./scripts/testAll.sh full
git status --short

Follow the release-candidate checks on this same fixed commit, including source restoration. The full code suite does not generate snapshot packages; package construction and native installation are separate checks.

3.2. Create and Transfer the Release Tag

Use an annotated tag on the approved commit. In one Bash session, select an unused version and the branch containing the approved workflow. This example prepares the stable v2 release; use an unused beta tag such as v2.0.0-beta-4 only when publishing another beta:

release_tag=v2.0.0
workflow_branch=main
git rev-parse "$release_commit^{commit}"
git show-ref --tags
git ls-remote --tags origin "refs/tags/$release_tag" "refs/tags/$release_tag^{}"

The selected tag must be absent locally and remotely. After transferring the approved branch through its normal PR/push workflow, verify that the remote branch contains the candidate, then create and transfer only that tag:

git fetch origin "$workflow_branch"
git merge-base --is-ancestor "$release_commit" "origin/$workflow_branch" &&
  git tag -a "$release_tag" "$release_commit" -m "Trice $release_tag" &&
  git push origin "refs/tags/$release_tag"
git rev-parse "$release_tag^{}"
git ls-remote --tags origin "refs/tags/$release_tag^{}"

The local commit and the remote annotated tag’s peeled commit must agree. Keep the tag fixed after publishing so its sources, tool metadata and documentation continue to describe the same release. A failed ancestry check means branch integration is incomplete; resolve it before tagging.

3.3. Start the Release Workflow

In GitHub Actions, open goreleaser, choose Run workflow, select the branch containing the approved pipeline, and enter the selected release tag in the required tag field.

The workflow checks out refs/tags/<tag>, checks its commit, and explicitly passes that tag to GoReleaser. The workflow branch selects the pipeline; the tag selects the sources and release version. In the same Bash session:

gh workflow run goreleaser.yml --repo rokath/trice --ref "$workflow_branch" -f tag="$release_tag"
gh run list --repo rokath/trice --workflow goreleaser.yml --limit 5

The workflow uses the selected version’s section in CHANGELOG.md as the release notes; a missing or empty section stops publication. The spelling must match exactly: v2.0.0-beta3 does not select the v2.0.0-beta-3 section. Existing tags are not renamed. Wait for the Run GoReleaser and Verify generated release artifacts steps to succeed.

The release configuration uses release.prerelease: auto and Homebrew skip_upload: auto:

Selected tag GitHub release Stable Homebrew tap
v2.0.0-beta-4 or another beta/RC tag Prerelease Unchanged; install the tagged archive or checkout.
v2.0.0 or another plain version Stable Updated with both trice and tlog.

3.4. Inspect the Published Assets

Open the release with the selected tag and check:

3.5. Audit That Exact Release

Start release-audit manually with the same tag. For example:

gh release view "$release_tag" --repo rokath/trice
gh workflow run release-audit.yml --repo rokath/trice --ref "$workflow_branch" -f tag="$release_tag"
gh run list --repo rokath/trice --workflow release-audit.yml --limit 5

The audit downloads that release explicitly and tests its archives, packages, target sources and PDFs. The host archive jobs also compile the PC feature tour against the unpacked target library, then verify text, JSON and KV with both shipped tools. Missing artifacts, changed licenses, incorrect fields or non-record JSON stdout fail the audit.

3.6. Install a Beta or a Stable Release

For a beta, download the matching platform archive from its tagged release and place its tools in PATH, or build from a checkout of that tag. Use the matching target sources and manuals.

The module remains github.com/rokath/trice. Versioned remote installation with a v2 tag is not supported without a /v2 module path; use the archive or local checkout build described above. See Go major version suffixes.

For a published stable release, run brew install rokath/tap/trice to install both tools. Beta audits skip the Homebrew job; stable audits include it. These checks verify the published files, separately from local configuration and release-notes tests.