Skip to content

chore: make vX.Y.Z the stable release channel (docs, Helm, reward tags) - #1695

Open
FenjuFu wants to merge 3 commits into
iflytek:mainfrom
FenjuFu:docs/release-channels
Open

FenjuFu wants to merge 3 commits into
iflytek:mainfrom
FenjuFu:docs/release-channels

Conversation

@FenjuFu

@FenjuFu FenjuFu commented Oct 3, 2026 •

Copy link
Copy Markdown
Member

Summary

Makes the existing SemVer release channel visible to deployers and downstream automation, makes the Helm chart deploy a release by default, and keeps the reward bot's reward-* / statistic-* tags from taking the "Latest" release or showing up in git describe.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Refactoring

Related Issue

Closes #1694

Changes

  • .github/scripts/count-reward.ts: create statistic-* releases with --latest=false. Without it, the API default (make_latest: true) made statistic-2026-09 the newest release from 2026-09-01 until v1.1.2 shipped.
  • docker/astronAgent/.env.example: document the image tag channels. latest tracks main, vX.Y.Z pins an exact release, and X.Y / X follow a release line. The default stays latest, so existing setups behave the same.
  • docs/guide/quick-start.md, docs/zh/guide/quick-start.md: add an optional "pin a stable release" step that checks out the tag before copying .env.example, so the compose files match the images.
  • docs/DEPLOYMENT_FAQ.md, docs/zh/DEPLOYMENT_FAQ.md: replace the stale v1.0.0-rc.x advice, and describe upgrading a pinned deployment by tag instead of git pull.
  • Helm chart: appVersion "latest" → "v1.1.2" (chart version 1.0.0 → 1.1.2). A new astron-agent.imageTag helper uses global.astronAgentVersion when it is set and falls back to .Chart.AppVersion when it is empty. values.yaml now defaults that value to "", and helm/README.md documents pinning. Setting global.astronAgentVersion=latest restores the previous behaviour exactly. From now on, appVersion needs a bump at each release; if it is missed, the chart stays on the previous stable release instead of following main.
  • Reward tags vs git describe: share-reward.ts tagged the PR merge commit and count-reward.ts tagged main HEAD, so these tags became the nearest tag for later commits. Of the last 400 commits on main, 36 describe as reward-1575-N-g… or statistic-2026-09-N-g…, compared with 12 as v1.1.1-N-g…, so most of the v1.1.1→v1.1.2 window reports a reward tag as its version. New tags now point at a parentless empty-tree commit created by .github/scripts/git.ts; its message keeps the merge commit SHA. Branches never reach that commit, so git describe (with or without --tags) only sees vX.Y.Z. Tag contents and creator dates, which count-reward.ts reads, are unchanged. Because the old git describe --match "statistic-*" pre-check in statistic-member-reward.yml cannot see detached tags, I removed it; count-reward.ts already exits when the previous month has no reward data.
    • The two existing tags (reward-1575, statistic-2026-09) are older than v1.1.2, so main and every future commit already describe correctly. I left them as they are, because re-pointing published tags would need a force-push and would leave stale copies in existing clones.

Testing

  • Existing tests pass

  • New tests added (if applicable)

  • Manual testing completed

  • Queried GHCR for all 10 images in docker-compose.yaml (core-*, console-*). Each has v1.1.2, 1.1.2, 1.1, 1 and latest. For core-agent, v1.1.2, 1.1.2, 1.1 and 1 resolve to the same digest (sha256:1eaed2…), and latest resolves to a different one (sha256:7033e8…, a build of main), so the tag semantics described in the docs match what is published.

  • Confirmed the v1.1.2 tag contains docker/astronAgent/.env.example and docker-compose-with-auth.yaml, so the documented git checkout vX.Y.Z && cp .env.example .env sequence works.

  • Helm (v4.2.4): helm lint passes. The default render uses :v1.1.2 for all 10 service images. With --set global.astronAgentVersion=latest, the render matches main byte-for-byte apart from the helm.sh/chart / app.kubernetes.io/version labels and the per-render random secrets. helm/astron-agent/tests/verify_tenant_bootstrap.py passes (7 positive modes, 13 negative cases). The only Helm changes on main since v1.1.2 are MinIO infrastructure changes, so main's chart is compatible with the v1.1.2 service images.

  • Reward tags, tested end-to-end in a sandbox repo (local bare remote, Deno 2.9) with a v1.0.0 tag and later commits. Running createDetachedCommit and the tagging and pushing code from share-reward.ts with a reward dated last month created reward-42 on a commit with no parents and the empty tree, and its message records the merge SHA. The unmodified count-reward.ts then found that tag by creator date, produced the correct summary (@bob, CNY RMB: 300), and pushed statistic-2026-10 on another detached commit. After that, git describe and git describe --tags still returned v1.0.0-2-g…, a fresh clone still received all three tags, and no git identity was left in the local config. The final gh release create call reached the real gh, which failed safely because the sandbox remote is not on GitHub.

  • --latest=false is the documented gh release create flag for not marking a release as latest. The next statistic-* run will confirm it; I could not trigger the scheduled workflow from a fork.

Checklist

  • Code follows project coding standards
  • Self-review completed
  • Documentation updated (if needed)
  • Breaking changes documented

…test

- Explain the image tag channels in .env.example: latest tracks main,
  vX.Y.Z pins a release, X.Y / X follow a release line
- Add an optional "pin a stable release" step to the quick start (en/zh)
- Replace the stale v1.0.0-rc.x advice in the deployment FAQ and describe
  upgrading a pinned deployment by tag
- Create monthly statistic-* releases with --latest=false so they no
  longer take the repository's Latest release from vX.Y.Z

Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
- Set appVersion to v1.1.2 (and chart version to match) instead of latest
- Add astron-agent.imageTag helper: global.astronAgentVersion overrides,
  empty falls back to .Chart.AppVersion
- Default global.astronAgentVersion to empty; "latest" still selects the
  rolling main build
- Document pinning a release in helm/README.md

Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
reward-* tags pointed at PR merge commits and statistic-* tags at main
HEAD, so they became the nearest tag for later commits: between v1.1.1
and v1.1.2, most commits on main described as reward-1575-N-g<sha>
instead of v1.1.1-N-g<sha>.

- Point new reward-* / statistic-* tags at a parentless empty-tree commit
  (the merge commit SHA is kept in its message) so they are never
  reachable from a branch; tag contents and dates are read as before
- Drop the describe-based "new commits since last statistic" check, which
  cannot see detached tags; count-reward.ts already exits when there is
  no reward data for the previous month

Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
@FenjuFu
FenjuFu force-pushed the docs/release-channels branch from b3d5756 to 28bebd4 Compare October 3, 2026 12:00
@FenjuFu FenjuFu changed the title docs: document stable release channel and keep reward releases off Latest chore: make vX.Y.Z the stable release channel (docs, Helm, reward tags) Oct 3, 2026

This branch has not been deployed

No deployments
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.

Document the stable release channel and keep reward releases from taking "Latest"

1 participant