feat: GitFlow workflow with beta/stable CI pipelines

- Add develop branch for integration
- Replace single ci.yml with 3 workflows: ci-pr (PR checks), ci-develop (beta releases), ci-main (stable releases)
- Add prerelease support in version.go (ldflags injection)
- Add tests for prerelease version formatting
- Document full GitFlow process, versioning, and contributing guide in README

💘 Generated with Crush

Assisted-by: GLM-5.1 via Crush <crush@charm.land>

.gitea/workflows/ci-develop.yml

@@ -0,0 +1,135 @@
+name: Beta Release
+
+on:
+  push:
+    branches: [develop]
+
+jobs:
+  beta:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.3'
+
+      - name: Cache Go modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            /root/go/pkg/mod
+            /home/runner/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./... -v -race -timeout 60s
+
+      - name: Determine version
+        id: version
+        run: |
+          BASE_VERSION=$(grep 'Version =' internal/version/version.go | cut -d'"' -f2)
+          COMMIT_COUNT=$(git rev-list --count $(git tag -l 'v*.beta.*' --sort=-v:refname | head -1)..HEAD 2>/dev/null || git rev-list --count HEAD)
+          BETA_NUM=$(git tag -l "v${BASE_VERSION}-beta.*" --sort=-v:refname | head -1 | grep -o 'beta\.[0-9]*' | grep -o '[0-9]*' || echo "0")
+          BETA_NUM=$((BETA_NUM + 1))
+          VERSION="v${BASE_VERSION}-beta.${BETA_NUM}"
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "base=${BASE_VERSION}" >> $GITHUB_OUTPUT
+          echo "beta_num=${BETA_NUM}" >> $GITHUB_OUTPUT
+          echo "Building beta release: ${VERSION}"
+
+      - name: Build all platforms
+        run: |
+          mkdir -p dist
+          VERSION=${{ steps.version.outputs.version }}
+          LDFLAGS="-s -w -X github.com/muyue/muyue/internal/version.Prerelease=${VERSION#v}"
+          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-amd64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-arm64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-amd64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-arm64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-amd64.exe ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=windows GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-arm64.exe ./cmd/muyue/
+
+      - name: Package archives
+        run: |
+          cd dist
+          sha256sum * > checksums.txt
+          tar czf muyue-linux-amd64.tar.gz muyue-linux-amd64
+          tar czf muyue-linux-arm64.tar.gz muyue-linux-arm64
+          tar czf muyue-darwin-amd64.tar.gz muyue-darwin-amd64
+          tar czf muyue-darwin-arm64.tar.gz muyue-darwin-arm64
+          zip muyue-windows-amd64.zip muyue-windows-amd64.exe
+          zip muyue-windows-arm64.zip muyue-windows-arm64.exe
+          rm -f muyue-linux-amd64 muyue-linux-arm64 muyue-darwin-amd64 muyue-darwin-arm64 muyue-windows-amd64.exe muyue-windows-arm64.exe
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          LAST_STABLE=$(git tag -l 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | grep -v '-' | head -1 || echo "")
+          if [ -n "$LAST_STABLE" ]; then
+            RANGE="${LAST_STABLE}..HEAD"
+          else
+            RANGE="HEAD~20..HEAD"
+          fi
+          echo "Generating changelog from ${RANGE}"
+          {
+            echo "## ${{ steps.version.outputs.version }} (Beta)"
+            echo ""
+            echo "### Commits since ${LAST_STABLE:-start}"
+            echo ""
+            git log ${RANGE} --pretty=format:"- %s (%h)" --no-merges
+            echo ""
+            echo ""
+            echo "> This is a **beta** release. Use at your own risk."
+          } > /tmp/beta_changelog.md
+          echo "path=/tmp/beta_changelog.md" >> $GITHUB_OUTPUT
+
+      - name: Create release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+        run: |
+          if [ -z "$GITEA_TOKEN" ]; then
+            echo "Warning: GITEATOKEN not set, skipping release"
+            exit 0
+          fi
+          VERSION=${{ steps.version.outputs.version }}
+          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
+          BODY=$(cat /tmp/beta_changelog.md)
+          RESPONSE=$(curl -s -X POST "${API}" \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{
+              \"tag_name\":\"${VERSION}\",
+              \"target_commitish\":\"develop\",
+              \"name\":\"muyue ${VERSION} (Beta)\",
+              \"body\":$(echo "$BODY" | jq -Rs .),
+              \"draft\":false,
+              \"prerelease\":true
+            }")
+          RELEASE_ID=$(echo "$RESPONSE" | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
+          if [ -z "$RELEASE_ID" ]; then
+            echo "Failed to create release:"
+            echo "$RESPONSE"
+            exit 1
+          fi
+          echo "Release ID: ${RELEASE_ID}"
+          UPLOAD_URL="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets"
+          for file in dist/*.tar.gz dist/*.zip dist/checksums.txt; do
+            filename=$(basename "$file")
+            echo "Uploading ${filename}..."
+            curl -s -X POST "${UPLOAD_URL}" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -F "attachment=@${file};filename=${filename}" > /dev/null
+          done
+          echo "Beta release ${VERSION} published!"

.gitea/workflows/ci-main.yml

@@ -0,0 +1,197 @@
+name: Stable Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  stable:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.3'
+
+      - name: Cache Go modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            /root/go/pkg/mod
+            /home/runner/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./... -v -race -timeout 60s
+
+      - name: Determine version
+        id: version
+        run: |
+          BASE_VERSION=$(grep 'Version =' internal/version/version.go | cut -d'"' -f2)
+          VERSION="v${BASE_VERSION}"
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "base=${BASE_VERSION}" >> $GITHUB_OUTPUT
+          echo "Building stable release: ${VERSION}"
+
+      - name: Build all platforms
+        run: |
+          mkdir -p dist
+          LDFLAGS="-s -w"
+          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-amd64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-arm64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-amd64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-arm64 ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-amd64.exe ./cmd/muyue/
+          CGO_ENABLED=0 GOOS=windows GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-arm64.exe ./cmd/muyue/
+
+      - name: Package archives
+        run: |
+          cd dist
+          sha256sum * > checksums.txt
+          tar czf muyue-linux-amd64.tar.gz muyue-linux-amd64
+          tar czf muyue-linux-arm64.tar.gz muyue-linux-arm64
+          tar czf muyue-darwin-amd64.tar.gz muyue-darwin-amd64
+          tar czf muyue-darwin-arm64.tar.gz muyue-darwin-arm64
+          zip muyue-windows-amd64.zip muyue-windows-amd64.exe
+          zip muyue-windows-arm64.zip muyue-windows-arm64.exe
+          rm -f muyue-linux-amd64 muyue-linux-arm64 muyue-darwin-amd64 muyue-darwin-arm64 muyue-windows-amd64.exe muyue-windows-arm64.exe
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git tag -l 'v[0-9]*.[0-9]*.[0-9]*' --sort=-v:refname | grep -v '-' | head -1 || echo "")
+          if [ -n "$PREV_TAG" ]; then
+            RANGE="${PREV_TAG}..HEAD"
+            echo "range=${RANGE}" >> $GITHUB_OUTPUT
+          else
+            RANGE="HEAD~30..HEAD"
+            echo "range=${RANGE}" >> $GITHUB_OUTPUT
+          fi
+          VERSION=${{ steps.version.outputs.version }}
+          DL_URL="${{ github.server_url }}/${{ github.repository }}/releases/download/${VERSION}"
+          {
+            echo "## ${VERSION}"
+            echo ""
+            echo "### Changes since ${PREV_TAG:-start}"
+            echo ""
+            git log ${RANGE} --pretty=format:"- %s (%h)" --no-merges
+            echo ""
+            echo ""
+            echo "### Downloads"
+            echo ""
+            echo "| Platform | File |"
+            echo "|----------|------|"
+            echo "| Linux x86_64 | [muyue-linux-amd64.tar.gz](${DL_URL}/muyue-linux-amd64.tar.gz) |"
+            echo "| Linux ARM64 | [muyue-linux-arm64.tar.gz](${DL_URL}/muyue-linux-arm64.tar.gz) |"
+            echo "| macOS Intel | [muyue-darwin-amd64.tar.gz](${DL_URL}/muyue-darwin-amd64.tar.gz) |"
+            echo "| macOS Apple Silicon | [muyue-darwin-arm64.tar.gz](${DL_URL}/muyue-darwin-arm64.tar.gz) |"
+            echo "| Windows x86_64 | [muyue-windows-amd64.zip](${DL_URL}/muyue-windows-amd64.zip) |"
+            echo "| Windows ARM64 | [muyue-windows-arm64.zip](${DL_URL}/muyue-windows-arm64.zip) |"
+            echo ""
+            echo "### Install"
+            echo ""
+            echo "**Linux (x86_64)**"
+            echo "\`\`\`bash"
+            echo "curl -sL ${DL_URL}/muyue-linux-amd64.tar.gz | tar xz"
+            echo "chmod +x muyue-linux-amd64"
+            echo "sudo mv muyue-linux-amd64 /usr/local/bin/muyue"
+            echo "\`\`\`"
+            echo ""
+            echo "**macOS (Apple Silicon)**"
+            echo "\`\`\`bash"
+            echo "curl -sL ${DL_URL}/muyue-darwin-arm64.tar.gz | tar xz"
+            echo "chmod +x muyue-darwin-arm64"
+            echo "sudo mv muyue-darwin-arm64 /usr/local/bin/muyue"
+            echo "\`\`\`"
+            echo ""
+            echo "**Windows (x86_64)**"
+            echo "\`\`\`powershell"
+            echo "Invoke-WebRequest -Uri \"${DL_URL}/muyue-windows-amd64.zip\" -OutFile \"muyue.zip\""
+            echo "Expand-Archive -Path \"muyue.zip\" -DestinationPath \".\""
+            echo "Move-Item muyue-windows-amd64.exe C:\\Windows\\muyue.exe"
+            echo "\`\`\`"
+          } > /tmp/stable_changelog.md
+          echo "path=/tmp/stable_changelog.md" >> $GITHUB_OUTPUT
+
+      - name: Update CHANGELOG.md
+        run: |
+          if [ ! -f CHANGELOG.md ]; then
+            echo "# Changelog" > CHANGELOG.md
+            echo "" >> CHANGELOG.md
+            echo "All notable changes to this project will be documented in this file." >> CHANGELOG.md
+            echo "" >> CHANGELOG.md
+            echo "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)." >> CHANGELOG.md
+            echo "" >> CHANGELOG.md
+          fi
+          NEW_ENTRY=$(cat /tmp/stable_changelog.md)
+          EXISTING=$(tail -n +6 CHANGELOG.md)
+          {
+            head -5 CHANGELOG.md
+            echo ""
+            echo "$NEW_ENTRY"
+            echo ""
+            echo "$EXISTING"
+          } > CHANGELOG.md.new
+          mv CHANGELOG.md.new CHANGELOG.md
+
+      - name: Commit changelog
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+        run: |
+          git config user.name "CI Bot"
+          git config user.email "ci@legion-muyue.fr"
+          git add CHANGELOG.md
+          git diff --cached --quiet && echo "No changelog changes" && exit 0
+          git commit -m "chore: update CHANGELOG for ${{ steps.version.outputs.version }}"
+          git push
+
+      - name: Create release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
+        run: |
+          if [ -z "$GITEA_TOKEN" ]; then
+            echo "Warning: GITEATOKEN not set, skipping release"
+            exit 0
+          fi
+          VERSION=${{ steps.version.outputs.version }}
+          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
+          BODY=$(cat /tmp/stable_changelog.md)
+          RESPONSE=$(curl -s -X POST "${API}" \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{
+              \"tag_name\":\"${VERSION}\",
+              \"target_commitish\":\"main\",
+              \"name\":\"muyue ${VERSION}\",
+              \"body\":$(echo "$BODY" | jq -Rs .),
+              \"draft\":false,
+              \"prerelease\":false
+            }")
+          RELEASE_ID=$(echo "$RESPONSE" | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
+          if [ -z "$RELEASE_ID" ]; then
+            echo "Failed to create release:"
+            echo "$RESPONSE"
+            exit 1
+          fi
+          echo "Release ID: ${RELEASE_ID}"
+          UPLOAD_URL="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets"
+          for file in dist/*.tar.gz dist/*.zip dist/checksums.txt; do
+            filename=$(basename "$file")
+            echo "Uploading ${filename}..."
+            curl -s -X POST "${UPLOAD_URL}" \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -F "attachment=@${file};filename=${filename}" > /dev/null
+          done
+          echo "Stable release ${VERSION} published!"

.gitea/workflows/ci-pr.yml

@@ -0,0 +1,40 @@
+name: PR Check
+
+on:
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.24.3'
+
+      - name: Cache Go modules
+        uses: actions/cache@v4
+        with:
+          path: |
+            /root/go/pkg/mod
+            /home/runner/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test ./... -v -race -timeout 60s
+
+      - name: Build
+        run: |
+          go build -o muyue ./cmd/muyue/
+          ./muyue version

.gitea/workflows/ci.yml

@@ -1,177 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: '1.24.3'
-
-      - name: Cache Go modules
-        uses: actions/cache@v4
-        with:
-          path: |
-            /root/go/pkg/mod
-            /home/runner/go/pkg/mod
-          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
-          restore-keys: |
-            ${{ runner.os }}-go-
-
-      - name: Download dependencies
-        run: go mod download
-
-      - name: Vet
-        run: go vet ./...
-
-      - name: Test
-        run: go test ./... -v -race -timeout 60s
-
-      - name: Build
-        run: |
-          go build -o muyue ./cmd/muyue/
-          ./muyue version
-
-      - name: Build all platforms
-        if: github.event_name == 'push'
-        run: |
-          mkdir -p dist
-          LDFLAGS="-s -w -X github.com/muyue/muyue/internal/version.Version=$(grep 'Version =' internal/version/version.go | cut -d'"' -f2)"
-          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-amd64 ./cmd/muyue/
-          CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-linux-arm64 ./cmd/muyue/
-          CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-amd64 ./cmd/muyue/
-          CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-darwin-arm64 ./cmd/muyue/
-          CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-amd64.exe ./cmd/muyue/
-          CGO_ENABLED=0 GOOS=windows GOARCH=arm64 go build -ldflags="$LDFLAGS" -o dist/muyue-windows-arm64.exe ./cmd/muyue/
-
-      - name: Package archives
-        if: github.event_name == 'push'
-        run: |
-          cd dist
-          sha256sum * > checksums.txt
-          tar czf muyue-linux-amd64.tar.gz muyue-linux-amd64
-          tar czf muyue-linux-arm64.tar.gz muyue-linux-arm64
-          tar czf muyue-darwin-amd64.tar.gz muyue-darwin-amd64
-          tar czf muyue-darwin-arm64.tar.gz muyue-darwin-arm64
-          zip muyue-windows-amd64.zip muyue-windows-amd64.exe
-          zip muyue-windows-arm64.zip muyue-windows-arm64.exe
-          rm -f muyue-linux-amd64 muyue-linux-arm64 muyue-darwin-amd64 muyue-darwin-arm64 muyue-windows-amd64.exe muyue-windows-arm64.exe
-
-      - name: Delete old release
-        if: github.event_name == 'push'
-        env:
-          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
-        run: |
-          if [ -z "$GITEA_TOKEN" ]; then
-            echo "Warning: GITEATOKEN not set"
-            exit 0
-          fi
-          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
-          RESPONSE=$(curl -s -H "Authorization: token ${GITEA_TOKEN}" "${API}" 2>/dev/null || echo "")
-          if [ -n "$RESPONSE" ]; then
-            echo "$RESPONSE" | grep -o '"id":[0-9]*' | while read line; do
-              ID=$(echo "$line" | grep -o '[0-9]*')
-              curl -s -X DELETE -H "Authorization: token ${GITEA_TOKEN}" "${API}/${ID}" > /dev/null 2>&1 || true
-            done || true
-          fi
-          curl -s -X DELETE -H "Authorization: token ${GITEA_TOKEN}" \
-            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/tags/latest" > /dev/null 2>&1 || true
-
-      - name: Create release
-        if: github.event_name == 'push'
-        env:
-          GITEA_TOKEN: ${{ secrets.GITEATOKEN }}
-        run: |
-          if [ -z "$GITEA_TOKEN" ]; then
-            echo "Error: GITEATOKEN not set"
-            exit 1
-          fi
-          SHORT_SHA=$(git rev-parse --short HEAD)
-          API="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
-          DL_URL="${{ github.server_url }}/${{ github.repository }}/releases/download/latest"
-          BODY=$(cat <<BODYEOF
-          ## muyue latest (${SHORT_SHA})
-
-          | Platform | File |
-          |----------|------|
-          | Linux x86_64 | muyue-linux-amd64.tar.gz |
-          | Linux ARM64 | muyue-linux-arm64.tar.gz |
-          | macOS Intel | muyue-darwin-amd64.tar.gz |
-          | macOS Apple Silicon | muyue-darwin-arm64.tar.gz |
-          | Windows x86_64 | muyue-windows-amd64.zip |
-          | Windows ARM64 | muyue-windows-arm64.zip |
-
-          ### Install
-
-          **Linux (x86_64)**
-          \`\`\`bash
-          curl -sL ${DL_URL}/muyue-linux-amd64.tar.gz | tar xz
-          chmod +x muyue-linux-amd64
-          sudo mv muyue-linux-amd64 /usr/local/bin/muyue
-          \`\`\`
-
-          **Linux (ARM64)**
-          \`\`\`bash
-          curl -sL ${DL_URL}/muyue-linux-arm64.tar.gz | tar xz
-          chmod +x muyue-linux-arm64
-          sudo mv muyue-linux-arm64 /usr/local/bin/muyue
-          \`\`\`
-
-          **macOS (Apple Silicon)**
-          \`\`\`bash
-          curl -sL ${DL_URL}/muyue-darwin-arm64.tar.gz | tar xz
-          chmod +x muyue-darwin-arm64
-          sudo mv muyue-darwin-arm64 /usr/local/bin/muyue
-          \`\`\`
-
-          **macOS (Intel)**
-          \`\`\`bash
-          curl -sL ${DL_URL}/muyue-darwin-amd64.tar.gz | tar xz
-          chmod +x muyue-darwin-amd64
-          sudo mv muyue-darwin-amd64 /usr/local/bin/muyue
-          \`\`\`
-
-          **Windows (x86_64)**
-          \`\`\`powershell
-          Invoke-WebRequest -Uri "${DL_URL}/muyue-windows-amd64.zip" -OutFile "muyue.zip"
-          Expand-Archive -Path "muyue.zip" -DestinationPath "."
-          Move-Item muyue-windows-amd64.exe C:\Windows\muyue.exe
-          \`\`\`
-
-          **Windows (ARM64)**
-          \`\`\`powershell
-          Invoke-WebRequest -Uri "${DL_URL}/muyue-windows-arm64.zip" -OutFile "muyue.zip"
-          Expand-Archive -Path "muyue.zip" -DestinationPath "."
-          Move-Item muyue-windows-arm64.exe C:\Windows\muyue.exe
-          \`\`\`
-          BODYEOF
-          )
-          RESPONSE=$(curl -s -X POST "${API}" \
-            -H "Authorization: token ${GITEA_TOKEN}" \
-            -H "Content-Type: application/json" \
-            -d "{\"tag_name\":\"latest\",\"target_commitish\":\"main\",\"name\":\"muyue latest (${SHORT_SHA})\",\"body\":$(echo "$BODY" | jq -Rs .),\"draft\":false,\"prerelease\":false}")
-          RELEASE_ID=$(echo "$RESPONSE" | grep -o '"id":[0-9]*' | head -1 | grep -o '[0-9]*')
-          if [ -z "$RELEASE_ID" ]; then
-            echo "Failed to create release:"
-            echo "$RESPONSE"
-            exit 1
-          fi
-          echo "Release ID: ${RELEASE_ID}"
-          UPLOAD_URL="${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets"
-          for file in dist/*.tar.gz dist/*.zip dist/checksums.txt; do
-            filename=$(basename "$file")
-            echo "Uploading ${filename}..."
-            curl -s -X POST "${UPLOAD_URL}" \
-              -H "Authorization: token ${GITEA_TOKEN}" \
-              -F "attachment=@${file};filename=${filename}" > /dev/null
-          done
-          echo "Release published!"

README.md

@@ -120,6 +120,152 @@ First run launches an interactive profiling wizard that:
 
 Built for Linux (primary), macOS, and Windows. WSL supported.
 
+## Contributing — GitFlow Workflow
+
+This project uses a **lightweight GitFlow** with 2 permanent branches and conventional commits.
+
+### Branch model
+
+```
+feature/xxx  ──PR (squash)──▶  develop  ──PR (merge)──▶  main
+fix/xxx      ──PR (squash)──▶  develop
+hotfix/xxx   ──PR (squash)──▶  main (+ backport develop)
+```
+
+| Branch | Purpose | Permanent? |
+|--------|---------|------------|
+| `main` | Production — stable releases only | Yes |
+| `develop` | Integration — all features merge here first | Yes |
+| `feature/*` | New feature or enhancement | No (deleted after merge) |
+| `fix/*` | Bug fix | No |
+| `hotfix/*` | Urgent fix on production | No |
+
+### Release channels
+
+| Event | Channel | Tag format | Prerelease? |
+|-------|---------|------------|-------------|
+| PR merge → `develop` | **Beta** | `vX.Y.Z-beta.N` | Yes |
+| Merge `develop` → `main` | **Stable** | `vX.Y.Z` | No |
+
+### CI/CD Pipelines
+
+| Workflow | Trigger | What it does |
+|----------|---------|--------------|
+| `ci-pr.yml` | PR to `main` or `develop` | vet + test + build (no release) |
+| `ci-develop.yml` | Push to `develop` | vet + test + build all platforms + create beta release |
+| `ci-main.yml` | Push to `main` | vet + test + build all platforms + update CHANGELOG.md + create stable release |
+
+### Step-by-step: contribute a feature
+
+```bash
+# 1. Create your branch from develop
+git checkout develop
+git pull
+git checkout -b feature/my-feature
+
+# 2. Work, commit with conventional messages
+git commit -m "feat: add amazing thing"
+git commit -m "docs: update usage"
+
+# 3. Push and create a PR to develop (squash merge)
+git push -u origin feature/my-feature
+# → Create PR on Gitea: feature/my-feature → develop
+# → CI runs ci-pr.yml (test + vet + build)
+# → Squash & merge the PR
+# → ci-develop.yml triggers: beta release created
+```
+
+### Step-by-step: release a stable version
+
+```bash
+# 1. Bump the version in internal/version/version.go
+#    Change: Version = "0.2.0"  →  Version = "0.3.0"
+#    Commit on develop:
+git checkout develop
+# (edit internal/version/version.go)
+git commit -m "chore: bump version to 0.3.0"
+git push
+
+# 2. Create a PR from develop to main
+# → CI runs ci-pr.yml (test + vet + build)
+# → Merge the PR
+# → ci-main.yml triggers:
+#    - Builds all platforms
+#    - Auto-generates changelog from conventional commits
+#    - Updates CHANGELOG.md
+#    - Creates stable release v0.3.0
+```
+
+### Step-by-step: hotfix on production
+
+```bash
+# 1. Create hotfix branch from main
+git checkout main
+git pull
+git checkout -b hotfix/critical-fix
+
+# 2. Fix and commit
+git commit -m "fix: resolve critical issue"
+
+# 3. Create PR to main (squash merge)
+# → CI runs, then ci-main.yml creates a new stable release
+
+# 4. Backport to develop
+git checkout develop
+git merge hotfix/critical-fix
+git push
+```
+
+### Versioning — How it works
+
+**The base version (`X.Y.Z`) is manual.** It lives in `internal/version/version.go`:
+
+```go
+const (
+    Version = "0.2.0"  // ← bump this before a release
+)
+```
+
+**The prerelease suffix is automatic:**
+
+- **Beta**: `ci-develop.yml` auto-increments `beta.N` by counting existing `vX.Y.Z-beta.*` tags
+- **Stable**: `ci-main.yml` uses the exact version from `version.go` (no suffix)
+
+Binary version is injected at build time via `-ldflags`:
+
+```bash
+# Beta build (automatic in CI)
+go build -ldflags="-X github.com/muyue/muyue/internal/version.Prerelease=beta.3" ./cmd/muyue/
+# → muyue v0.2.0-beta.3
+
+# Stable build (automatic in CI)
+go build -ldflags="-s -w" ./cmd/muyue/
+# → muyue v0.2.0
+```
+
+### Conventional commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages:
+
+| Prefix | Use for | Example |
+|--------|---------|---------|
+| `feat:` | New feature | `feat: add Docker support` |
+| `fix:` | Bug fix | `fix: correct config path on Windows` |
+| `docs:` | Documentation | `docs: add API reference` |
+| `chore:` | Maintenance | `chore: bump version to 0.3.0` |
+| `refactor:` | Code restructuring | `refactor: split scanner module` |
+| `perf:` | Performance | `perf: cache scanner results` |
+| `test:` | Tests | `test: add config unit tests` |
+| `ci:` | CI/CD changes | `ci: add beta release workflow` |
+| `security:` | Security fixes | `security: encrypt API keys at rest` |
+
+### Branch protection (configure in Gitea UI)
+
+- **`main`**: Require PR + passing CI + at least 1 approval
+- **`develop`**: Require PR + passing CI
+- **Squash merge**: Enabled by default for PRs to `develop`
+- **Merge commit**: For PRs from `develop` to `main`
+
 ## License
 
 MIT

internal/version/version.go

@@ -7,6 +7,12 @@ const (
 	License = "MIT"
 )
 
+var Prerelease string
+
 func FullVersion() string {
-	return Name + " v" + Version
+	v := Name + " v" + Version
+	if Prerelease != "" {
+		v += "-" + Prerelease
+	}
+	return v
 }

internal/version/version_test.go

@@ -15,6 +15,28 @@ func TestFullVersion(t *testing.T) {
 	}
 }
 
+func TestFullVersionWithPrerelease(t *testing.T) {
+	original := Prerelease
+	Prerelease = "beta.1"
+	defer func() { Prerelease = original }()
+
+	v := FullVersion()
+	if !strings.Contains(v, "beta.1") {
+		t.Errorf("FullVersion should contain prerelease suffix, got %s", v)
+	}
+}
+
+func TestFullVersionWithoutPrerelease(t *testing.T) {
+	original := Prerelease
+	Prerelease = ""
+	defer func() { Prerelease = original }()
+
+	v := FullVersion()
+	if strings.Contains(v, "-") {
+		t.Errorf("FullVersion should not contain prerelease suffix, got %s", v)
+	}
+}
+
 func TestConstants(t *testing.T) {
 	if Name == "" {
 		t.Error("Name should not be empty")