From cea58108c1d1ffda87ce5a6d862992b8ee2fc0bd Mon Sep 17 00:00:00 2001
From: Subin Lee <chandar.sblee@gmail.com>
Date: Fri, 8 May 2026 10:37:55 +0900
Subject: [PATCH] feat(release): add preview build artifacts and guide to
 release-please PRs

When release-please opens or updates a release PR, build snapshot
binaries for every supported OS/arch via GoReleaser, upload them as a
workflow artifact, and post (or idempotently update) a Korean
download/usage guide as a PR comment. Reviewers can verify the next
version end-to-end before merging the release PR.

- Add preview-release-pr job to .github/workflows/release-please.yml
- Add comment body template at .github/templates/preview-build-comment.md.tmpl
- Add snapshot.version_template to .goreleaser.yaml so the binary
  version matches the preview tag and resolves the v2.2 deprecation

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../templates/preview-build-comment.md.tmpl   |  71 +++++++++
 .github/workflows/release-please.yml          | 135 ++++++++++++++++++
 .goreleaser.yaml                              |   3 +
 3 files changed, 209 insertions(+)
 create mode 100644 .github/templates/preview-build-comment.md.tmpl

diff --git a/.github/templates/preview-build-comment.md.tmpl b/.github/templates/preview-build-comment.md.tmpl
new file mode 100644
index 0000000..c9286bb
--- /dev/null
+++ b/.github/templates/preview-build-comment.md.tmpl
@@ -0,0 +1,71 @@
+<!-- preview-build -->
+## 📦 v${VERSION} Preview Build
+
+Release Please가 다음 릴리즈를 준비 중입니다: **v${VERSION}** (commit `${SHORT_SHA}`).
+이 PR이 머지되면 정식 릴리즈가 자동으로 생성됩니다. 머지 전에 아래 미리보기 바이너리로 새 버전을 검증할 수 있습니다.
+
+> [!IMPORTANT]
+> 이 바이너리는 **공식 릴리즈가 아닙니다.** GitHub Actions Artifact는 약 **14일 후 자동 삭제**되며 다운로드에는 GitHub 로그인이 필요합니다.
+
+### 다운로드
+
+**옵션 A — GitHub CLI (권장)**
+
+```bash
+gh run download ${RUN_ID} \
+  --repo ${REPO} \
+  --name ${ARTIFACT_NAME} \
+  --dir solactl-preview
+cd solactl-preview
+```
+
+**옵션 B — 웹 브라우저**
+
+[Workflow Run #${RUN_ID}](${RUN_URL}) 페이지 하단 _Artifacts_ 섹션에서 [`${ARTIFACT_NAME}`](${ARTIFACT_URL}) 을 받아 압축을 풉니다. 다운로드 받은 zip 안에는 OS/아키텍처별 tarball·zip 과 `checksums.txt` 가 들어 있습니다.
+
+### 실행
+
+#### Linux / macOS
+
+플랫폼에 맞는 tarball을 풉니다 (`<OS>` = `linux` 또는 `darwin`, `<ARCH>` = `amd64` 또는 `arm64`):
+
+```bash
+tar -xzf solactl_${VERSION}-preview-${SHORT_SHA}_<OS>_<ARCH>.tar.gz
+chmod +x solactl
+./solactl version
+# 예상 출력: solactl ${VERSION}-preview-${SHORT_SHA} (commit: ..., date: ...)
+```
+
+> [!NOTE]
+> macOS에서 _"확인되지 않은 개발자"_ 경고가 뜨면 quarantine 속성을 제거하세요:
+> ```bash
+> xattr -d com.apple.quarantine ./solactl
+> ```
+
+#### Windows
+
+```powershell
+Expand-Archive solactl_${VERSION}-preview-${SHORT_SHA}_windows_amd64.zip -DestinationPath .
+.\solactl_${VERSION}-preview-${SHORT_SHA}_windows_amd64\solactl.exe version
+```
+
+### 무결성 검증 (선택)
+
+```bash
+sha256sum -c checksums.txt --ignore-missing
+```
+
+### 검증 포인트
+
+머지 전에 아래 항목들을 확인해 주세요:
+
+- 이 PR 상단의 _Release notes_ 에 나열된 변경 사항이 의도대로 동작하는지
+- `solactl version` 출력이 위 예상 출력과 일치하는지
+- 회귀 가능성이 있는 기존 명령들 (`solactl configure`, `solactl send sms`, `solactl quota`, `solactl kakao` 등)
+- 자주 쓰는 워크플로 (설정 파일 생성·로드, `--profile` 전환, `--debug` 출력)
+
+문제가 있다면 이 PR에 코멘트로 알려주세요. 머지 후 release 워크플로가 자동으로 정식 바이너리를 빌드·배포합니다.
+
+---
+
+<sub>이 댓글은 <code>.github/workflows/release-please.yml</code> 의 <code>preview-release-pr</code> job 에 의해 자동으로 생성·갱신됩니다 · build commit <code>${SHA}</code> · run [#${RUN_ID}](${RUN_URL})</sub>
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
index 140c0fc..d24d88d 100644
--- a/.github/workflows/release-please.yml
+++ b/.github/workflows/release-please.yml
@@ -145,6 +145,141 @@ jobs:
           gh api "repos/$REPO/statuses/$SHA" \
             -f state=failure -f context="Lint" -f description="Lint failed"
 
+  preview-release-pr:
+    name: Preview Build (Release PR)
+    needs: release-please
+    if: ${{ !needs.release-please.outputs.release_created && needs.release-please.outputs.pr_head_sha != '' }}
+    runs-on: ubuntu-latest
+    env:
+      ARTIFACT_NAME_PREFIX: solactl-preview
+    steps:
+      - name: Set pending status
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ needs.release-please.outputs.pr_head_sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api "repos/$REPO/statuses/$SHA" \
+            -f state=pending -f context="Preview Build" -f description="Building preview binaries..."
+
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ needs.release-please.outputs.pr_head_sha }}
+          fetch-depth: 0
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.26.1'
+
+      - name: Resolve preview version
+        id: version
+        run: |
+          VERSION=$(jq -r '."."' .release-please-manifest.json)
+          if [ -z "$VERSION" ] || [ "$VERSION" = "null" ]; then
+            echo "::error::Failed to read version from .release-please-manifest.json"
+            exit 1
+          fi
+          SHORT_SHA="${GITHUB_SHA::7}"
+          TAG="v${VERSION}-preview-${SHORT_SHA}"
+          ARTIFACT_NAME="${ARTIFACT_NAME_PREFIX}-v${VERSION}-${SHORT_SHA}"
+          {
+            echo "version=${VERSION}"
+            echo "short_sha=${SHORT_SHA}"
+            echo "tag=${TAG}"
+            echo "artifact_name=${ARTIFACT_NAME}"
+          } >> "$GITHUB_OUTPUT"
+          echo "GORELEASER_CURRENT_TAG=${TAG}" >> "$GITHUB_ENV"
+
+      - name: Run GoReleaser snapshot
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          distribution: goreleaser
+          version: '~> v2'
+          args: release --snapshot --skip=publish --clean
+
+      - name: Upload preview artifacts
+        id: artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.version.outputs.artifact_name }}
+          path: |
+            dist/solactl_*.tar.gz
+            dist/solactl_*.zip
+            dist/checksums.txt
+          retention-days: 14
+          if-no-files-found: error
+          compression-level: 0
+
+      - name: Comment preview guide on PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          VERSION: ${{ steps.version.outputs.version }}
+          SHORT_SHA: ${{ steps.version.outputs.short_sha }}
+          TAG: ${{ steps.version.outputs.tag }}
+          SHA: ${{ needs.release-please.outputs.pr_head_sha }}
+          ARTIFACT_URL: ${{ steps.artifact.outputs.artifact-url }}
+          ARTIFACT_NAME: ${{ steps.version.outputs.artifact_name }}
+          RUN_ID: ${{ github.run_id }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          TEMPLATE_PATH: .github/templates/preview-build-comment.md.tmpl
+        run: |
+          set -euo pipefail
+
+          if [ ! -f "$TEMPLATE_PATH" ]; then
+            echo "::error::Comment template not found at $TEMPLATE_PATH"
+            exit 1
+          fi
+
+          PR_NUMBER=$(gh pr list --repo "$REPO" --head release-please--branches--main --state open --json number --jq '.[0].number')
+          if [ -z "$PR_NUMBER" ]; then
+            echo "::warning::No open release-please PR found; skipping comment"
+            exit 0
+          fi
+
+          export VERSION SHORT_SHA TAG SHA ARTIFACT_NAME ARTIFACT_URL RUN_ID RUN_URL REPO
+
+          BODY_FILE="$(mktemp)"
+          envsubst '${VERSION} ${SHORT_SHA} ${TAG} ${SHA} ${ARTIFACT_NAME} ${ARTIFACT_URL} ${RUN_ID} ${RUN_URL} ${REPO}' \
+            < "$TEMPLATE_PATH" > "$BODY_FILE"
+
+          PAYLOAD_FILE="$(mktemp)"
+          jq -Rs '{body: .}' "$BODY_FILE" > "$PAYLOAD_FILE"
+
+          EXISTING_ID=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" --paginate \
+            --jq '.[] | select(.body | startswith("<!-- preview-build -->")) | .id' | head -n 1)
+
+          if [ -n "$EXISTING_ID" ]; then
+            echo "Updating existing preview comment $EXISTING_ID on PR #$PR_NUMBER"
+            gh api -X PATCH "repos/$REPO/issues/comments/$EXISTING_ID" --input "$PAYLOAD_FILE" > /dev/null
+          else
+            echo "Creating new preview comment on PR #$PR_NUMBER"
+            gh api "repos/$REPO/issues/$PR_NUMBER/comments" --input "$PAYLOAD_FILE" > /dev/null
+          fi
+
+      - name: Report success
+        if: success()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ needs.release-please.outputs.pr_head_sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api "repos/$REPO/statuses/$SHA" \
+            -f state=success -f context="Preview Build" -f description="Preview binaries ready"
+
+      - name: Report failure
+        if: failure()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SHA: ${{ needs.release-please.outputs.pr_head_sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api "repos/$REPO/statuses/$SHA" \
+            -f state=failure -f context="Preview Build" -f description="Preview build failed"
+
   goreleaser:
     name: Release Binaries
     needs: release-please
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 3f509d2..4691211 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -31,6 +31,9 @@ archives:
 checksum:
   name_template: checksums.txt
 
+snapshot:
+  version_template: '{{ .Version }}'
+
 changelog:
   disable: true