release: define preview tag strategy and rollback guide for Homebrew preview channel

[sharkAndshark]

Background

The Homebrew preview channel is now updated automatically by the nightly workflow on main, and the end-to-end path has already been validated in GitHub Actions:

• PR Fix nightly Homebrew tap update GH CLI authentication #153 merged the main-branch guard and GH CLI authentication fix for tap updates
• Manual nightly run 22908891361 completed successfully
• update_homebrew_tap completed successfully, including Generate formula and Update tap repository

This means the current nightly -> release -> formula generation -> tap update path is working.

However, the release policy for the preview channel is still incomplete in two important areas:

1. We are still publishing Homebrew preview from nightly tags rather than semantic preview tags
2. We do not yet have an explicit rollback / pinning guide for users before upgrade or after a bad preview release

Problem

Using nightly tags as the long-term public Homebrew preview contract is workable, but it is not ideal:

• users do not get a stable, human-readable preview version line such as v0.1.0-preview.1
• rollback guidance is unclear when a preview build breaks compatibility or introduces regressions
• release intent is mixed: nightly builds are CI artifacts, while preview builds are user-facing distribution artifacts

We should explicitly define how the preview channel evolves from the current nightly-based mechanism to a semantic preview release policy, and document how users can safely recover or pin an older version.

Scope

This issue is about release policy and release-process documentation / automation design. It is not about changing the current working nightly->tap pipeline immediately unless needed to support the agreed policy.

Proposed Work

1. Define the trigger policy for semantic preview tags

• Decide when to cut preview tags from main
• Decide whether preview tags are manual, workflow-dispatch driven, or promoted from a specific nightly
• Decide naming convention, for example v0.1.0-preview.1

2. Define how Homebrew preview should track releases

• Decide whether mapflow-preview should always point to the latest semantic preview tag
• Decide whether nightly-based tap updates remain as an interim mechanism only
• Decide the migration plan from nightly tags to semantic preview tags

3. Define rollback / pinning guidance

• How users pin a specific preview version in Homebrew
• What data backup guidance we require before upgrade, especially ~/.mapflow
• What maintainers should do if a bad preview release has already been pushed to the tap

4. Update repository documentation

• docs/internal.md
• docs/dev/todo.md
• README / README_zh if user-facing install semantics change
• Any release runbook or release workflow docs that become necessary

5. Decide whether workflow changes are needed

• separate workflow for semantic preview release
• promotion path from nightly artifacts to preview artifacts
• extra assertions that the tap formula points to the intended tag

Acceptance Criteria

• A documented decision exists for semantic preview tagging policy
• A documented rollback / pinning guide exists for the preview channel
• The transition plan from nightly-based preview distribution to semantic preview tags is explicit
• Repository docs are updated to match the chosen policy
• If automation changes are needed, they are captured in follow-up implementation tasks or PRs

References

• docs/dev/todo.md Homebrew Preview Distribution section
• docs/internal.md Homebrew Preview notes
• PR Fix nightly Homebrew tap update GH CLI authentication #153
• Nightly workflow run 22908891361