Add a new branch cut GH workflow, and adopt setuptools-scm for version control (#15985)

.github/workflows/release-branch-cut.yml

@@ -0,0 +1,156 @@
+name: Release Branch Cut
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch_name:
+        description: 'Branch name to create (e.g., release/v0.5.7)'
+        required: true
+        type: string
+      commit_sha:
+        description: 'Commit SHA from main to cut the release branch from (defaults to latest main)'
+        required: false
+        type: string
+        default: ''
+
+permissions:
+  contents: write
+
+jobs:
+  cut-release-branch:
+    if: github.repository == 'sgl-project/sglang'
+    runs-on: ubuntu-latest
+    environment: 'prod'
+    outputs:
+      branch_name: ${{ steps.set_output.outputs.branch_name }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Validate branch name
+        run: |
+          BRANCH_NAME="${{ github.event.inputs.branch_name }}"
+
+          if [ -z "$BRANCH_NAME" ]; then
+            echo "::error::Branch name is required"
+            exit 1
+          fi
+
+          # Validate branch name format (should start with release/)
+          if [[ ! "$BRANCH_NAME" =~ ^release/ ]]; then
+            echo "::warning::Branch name '$BRANCH_NAME' does not follow convention 'release/vX.Y.Z'"
+          fi
+
+          echo "Branch name: $BRANCH_NAME"
+
+      - name: Validate commit SHA
+        id: validate
+        run: |
+          COMMIT_SHA="${{ github.event.inputs.commit_sha }}"
+
+          # If no commit SHA provided, use latest main
+          if [ -z "$COMMIT_SHA" ]; then
+            COMMIT_SHA=$(git rev-parse HEAD)
+            echo "No commit SHA provided, using latest main: $COMMIT_SHA"
+          fi
+
+          # Verify the commit exists and is on main
+          if ! git cat-file -t "$COMMIT_SHA" > /dev/null 2>&1; then
+            echo "::error::Commit SHA '$COMMIT_SHA' does not exist"
+            exit 1
+          fi
+
+          # Check if commit is an ancestor of main (i.e., is on main branch)
+          if ! git merge-base --is-ancestor "$COMMIT_SHA" main; then
+            echo "::error::Commit SHA '$COMMIT_SHA' is not on the main branch"
+            exit 1
+          fi
+
+          echo "COMMIT_SHA=$COMMIT_SHA" >> $GITHUB_OUTPUT
+          echo "Validated commit SHA: $COMMIT_SHA"
+
+      - name: Check if branch already exists
+        run: |
+          BRANCH_NAME="${{ github.event.inputs.branch_name }}"
+
+          if git ls-remote --heads origin "$BRANCH_NAME" | grep -q "$BRANCH_NAME"; then
+            echo "::error::Branch '$BRANCH_NAME' already exists"
+            exit 1
+          fi
+
+          echo "Branch '$BRANCH_NAME' does not exist, proceeding with creation"
+
+      - name: Create and push release branch
+        id: set_output
+        run: |
+          COMMIT_SHA="${{ steps.validate.outputs.COMMIT_SHA }}"
+          BRANCH_NAME="${{ github.event.inputs.branch_name }}"
+
+          git config user.name "sglang-bot"
+          git config user.email "sglang-bot@users.noreply.github.com"
+
+          # Create branch from the specified commit
+          git checkout -b "$BRANCH_NAME" "$COMMIT_SHA"
+
+          # Push the new branch
+          git push origin "$BRANCH_NAME"
+
+          echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
+          echo "Successfully created and pushed branch '$BRANCH_NAME' from commit '$COMMIT_SHA'"
+
+      - name: Summary
+        run: |
+          COMMIT_SHA="${{ steps.validate.outputs.COMMIT_SHA }}"
+          BRANCH_NAME="${{ github.event.inputs.branch_name }}"
+
+          echo "## Release Branch Cut Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "| Property | Value |" >> $GITHUB_STEP_SUMMARY
+          echo "|----------|-------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Branch | \`$BRANCH_NAME\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Commit | \`$COMMIT_SHA\` |" >> $GITHUB_STEP_SUMMARY
+          echo "| Triggered by | @${{ github.actor }} |" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
+          echo "1. Tests are automatically triggered on the release branch" >> $GITHUB_STEP_SUMMARY
+          echo "2. Apply any hotfixes if needed" >> $GITHUB_STEP_SUMMARY
+          echo "3. Create a tag to trigger release: \`gh workflow run release-tag.yml -f version=X.Y.Z -f ref=$BRANCH_NAME\`" >> $GITHUB_STEP_SUMMARY
+
+  run-nightly-tests-nvidia:
+    needs: cut-release-branch
+    uses: ./.github/workflows/nightly-test-nvidia.yml
+    with:
+      ref: ${{ needs.cut-release-branch.outputs.branch_name }}
+    secrets: inherit
+
+  run-nightly-tests-amd:
+    needs: cut-release-branch
+    uses: ./.github/workflows/nightly-test-amd.yml
+    with:
+      ref: ${{ needs.cut-release-branch.outputs.branch_name }}
+    secrets: inherit
+
+  run-nightly-tests-npu:
+    needs: cut-release-branch
+    uses: ./.github/workflows/nightly-test-npu.yml
+    with:
+      ref: ${{ needs.cut-release-branch.outputs.branch_name }}
+    secrets: inherit
+
+  run-pr-tests-xeon:
+    needs: cut-release-branch
+    uses: ./.github/workflows/pr-test-xeon.yml
+    with:
+      ref: ${{ needs.cut-release-branch.outputs.branch_name }}
+    secrets: inherit
+
+  run-pr-tests-xpu:
+    needs: cut-release-branch
+    uses: ./.github/workflows/pr-test-xpu.yml
+    with:
+      ref: ${{ needs.cut-release-branch.outputs.branch_name }}
+    secrets: inherit

.github/workflows/release-docker-amd.yml

@@ -1,11 +1,13 @@
 name: Release Docker Images (AMD)
 on:
   push:
-    branches:
-      - main
-    paths:
-      - "python/sglang/version.py"
+    tags:
+      - 'v[0-9]+.*'
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to build (without v prefix, e.g., 0.5.7)'
+        required: true
 
 jobs:
   publish:
@@ -26,9 +28,31 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      - name: Get version from tag
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Extract version from tag (e.g., v0.5.7 -> 0.5.7)
+            VERSION="${GITHUB_REF_NAME#v}"
+          fi
+
+          # Validate version format
+          if [ -z "$VERSION" ]; then
+            echo "::error::Version is empty"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Invalid version format: $VERSION (expected: X.Y.Z)"
+            exit 1
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
       - name: Build and Push
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
           echo "Version: ${version}"
 
           if [ "${{ matrix.gpu_arch }}" = "gfx942" ]; then
@@ -44,5 +68,6 @@ jobs:
 
           tag=v${version}-${rocm_tag}
 
-          docker build . -f docker/rocm.Dockerfile --build-arg BUILD_TYPE=${{ matrix.build_type }} --build-arg GPU_ARCH=${{ matrix.gpu_arch }} -t lmsysorg/sglang:${tag} --no-cache
+          # rocm.Dockerfile expects SGL_BRANCH with 'v' prefix for git tag checkout
+          docker build . -f docker/rocm.Dockerfile --build-arg BUILD_TYPE=${{ matrix.build_type }} --build-arg GPU_ARCH=${{ matrix.gpu_arch }} --build-arg SGL_BRANCH=v${version} -t lmsysorg/sglang:${tag} --no-cache
           docker push lmsysorg/sglang:${tag}

.github/workflows/release-docker.yml

@@ -12,11 +12,13 @@ name: Release Docker Images
 #
 on:
   push:
-    branches:
-      - main
-    paths:
-      - "python/sglang/version.py"
+    tags:
+      - 'v[0-9]+.*'
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to build (without v prefix, e.g., 0.5.7)'
+        required: true
 
 jobs:
   publish-x86:
@@ -56,9 +58,31 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and Push AMD64 Framework
+      - name: Get version from tag
+        id: version
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Extract version from tag (e.g., v0.5.7 -> 0.5.7)
+            VERSION="${GITHUB_REF_NAME#v}"
+          fi
+
+          # Validate version format
+          if [ -z "$VERSION" ]; then
+            echo "::error::Version is empty"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Invalid version format: $VERSION (expected: X.Y.Z)"
+            exit 1
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Build AMD64 Framework
+        run: |
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu129-amd64
 
           docker buildx build \
@@ -70,13 +94,14 @@ jobs:
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg GRACE_BLACKWELL=${{ matrix.variant.grace_blackwell }} \
             --build-arg INSTALL_FLASHINFER_JIT_CACHE=1 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
 
       - name: Build and Push AMD64 Runtime
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu129-amd64-runtime
 
           docker buildx build \
@@ -88,13 +113,14 @@ jobs:
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg GRACE_BLACKWELL=${{ matrix.variant.grace_blackwell }} \
             --build-arg INSTALL_FLASHINFER_JIT_CACHE=1 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
 
       - name: Build and Push AMD64 Runtime (CUDA 13)
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu130-amd64-runtime
 
           docker buildx build \
@@ -106,6 +132,7 @@ jobs:
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg INSTALL_FLASHINFER_JIT_CACHE=1 \
             --build-arg GRACE_BLACKWELL=0 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
@@ -136,9 +163,31 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Build and Push ARM64 Framework
+      - name: Get version from tag
+        id: version
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Extract version from tag (e.g., v0.5.7 -> 0.5.7)
+            VERSION="${GITHUB_REF_NAME#v}"
+          fi
+
+          # Validate version format
+          if [ -z "$VERSION" ]; then
+            echo "::error::Version is empty"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Invalid version format: $VERSION (expected: X.Y.Z)"
+            exit 1
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Build ARM64 Framework
+        run: |
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu129-arm64
 
           docker buildx build \
@@ -150,13 +199,14 @@ jobs:
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg GRACE_BLACKWELL=${{ matrix.variant.grace_blackwell }} \
             --build-arg INSTALL_FLASHINFER_JIT_CACHE=1 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
 
       - name: Build and Push ARM64 Runtime
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu129-arm64-runtime
 
           docker buildx build \
@@ -168,13 +218,14 @@ jobs:
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg GRACE_BLACKWELL=${{ matrix.variant.grace_blackwell }} \
             --build-arg INSTALL_FLASHINFER_JIT_CACHE=1 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
 
       - name: Build and Push ARM64 Runtime (CUDA 13)
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
           tag=v${version}-cu130-arm64-runtime
 
           docker buildx build \
@@ -185,6 +236,7 @@ jobs:
             --build-arg CUDA_VERSION=13.0.1 \
             --build-arg BUILD_TYPE=${{ matrix.variant.build_type }} \
             --build-arg GRACE_BLACKWELL=1 \
+            --build-arg SGL_VERSION=${version} \
             -t lmsysorg/sglang:${tag} \
             --no-cache \
             .
@@ -207,9 +259,31 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      - name: Get version from tag
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            # Extract version from tag (e.g., v0.5.7 -> 0.5.7)
+            VERSION="${GITHUB_REF_NAME#v}"
+          fi
+
+          # Validate version format
+          if [ -z "$VERSION" ]; then
+            echo "::error::Version is empty"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Invalid version format: $VERSION (expected: X.Y.Z)"
+            exit 1
+          fi
+
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
       - name: Create multi-arch manifests
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
+          version=${{ steps.version.outputs.version }}
 
           # Create versioned framework manifest (default)
           docker buildx imagetools create \

.github/workflows/release-pypi-nightly.yml

@@ -24,78 +24,51 @@ jobs:
     if: github.repository == 'sgl-project/sglang'
     runs-on: ubuntu-latest
     outputs:
-      nightly_version: ${{ steps.gen_version.outputs.nightly_version }}
-      commit_hash: ${{ steps.gen_version.outputs.commit_hash }}
-      build_date: ${{ steps.gen_version.outputs.build_date }}
+      nightly_version: ${{ steps.build.outputs.nightly_version }}
+      commit_hash: ${{ steps.build.outputs.commit_hash }}
+      build_date: ${{ steps.build.outputs.build_date }}
     steps:
       - uses: actions/checkout@v4
         with:
           # Use commit from: 1) Docker workflow, 2) manual input, 3) latest main
           ref: ${{ github.event.client_payload.commit_sha || inputs.commit_sha || github.sha }}
-          fetch-depth: 0  # Need full history for version generation
+          fetch-depth: 0  # Need full history for setuptools-scm
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.10"
 
-      - name: Generate nightly version
-        id: gen_version
+      - name: Install build dependencies
         run: |
-          # Get base version from version.py
-          BASE_VERSION=$(cat python/sglang/version.py | cut -d'"' -f2)
+          pip install build wheel setuptools setuptools-scm
+
+      - name: Build wheel
+        id: build
+        run: |
+          cd python
+          cp ../README.md ../LICENSE .
+
+          # Build wheel - setuptools-scm automatically generates version from git tags
+          python3 -m build --wheel
+
+          # Extract version from built wheel filename
+          WHEEL_FILE=$(ls dist/*.whl)
+          NIGHTLY_VERSION=$(echo "$WHEEL_FILE" | sed 's/.*sglang-\(.*\)-py3.*/\1/')
 
           # Get commit info
           COMMIT_HASH=$(git rev-parse --short HEAD)
-          COMMIT_COUNT=$(git rev-list --count HEAD)
-
-          # Get current date in YYYY-MM-DD format for release tag
           BUILD_DATE=$(date -u +%Y-%m-%d)
-          # Get compact date format for wheel filename (YYYYMMDD)
-          BUILD_DATE_COMPACT=$(date -u +%Y%m%d)
 
-          # Generate nightly version following PEP 440
-          # Format: {base_version}.dev{commit_count}+{date}.g{commit_hash}
-          NIGHTLY_VERSION="${BASE_VERSION}.dev${COMMIT_COUNT}+${BUILD_DATE_COMPACT}.g${COMMIT_HASH}"
-
-          echo "Base version: ${BASE_VERSION}"
+          echo "Built wheel: $WHEEL_FILE"
           echo "Nightly version: ${NIGHTLY_VERSION}"
           echo "Commit: ${COMMIT_HASH}"
           echo "Build date: ${BUILD_DATE}"
 
           echo "nightly_version=${NIGHTLY_VERSION}" >> $GITHUB_OUTPUT
           echo "commit_hash=${COMMIT_HASH}" >> $GITHUB_OUTPUT
-          echo "base_version=${BASE_VERSION}" >> $GITHUB_OUTPUT
           echo "build_date=${BUILD_DATE}" >> $GITHUB_OUTPUT
 
-      - name: Update pyproject.toml with nightly version
-        run: |
-          cd python
-          BASE_VERSION=$(cat sglang/version.py | cut -d'"' -f2)
-          NIGHTLY_VERSION="${{ steps.gen_version.outputs.nightly_version }}"
-
-          # Update version (temporary, not committed)
-          sed -i "s/version = \"${BASE_VERSION}\"/version = \"${NIGHTLY_VERSION}\"/" pyproject.toml
-
-          # Verify update
-          echo "Updated version in pyproject.toml:"
-          grep "^version" pyproject.toml
-
-      - name: Install build dependencies
-        run: |
-          cd python
-          pip install build wheel setuptools
-
-      - name: Build wheel
-        run: |
-          cd python
-          cp ../README.md ../LICENSE .
-          python3 -m build --wheel
-
-          # List built wheels
-          echo "Built wheel:"
-          ls -lh dist/
-
       - name: Upload wheel artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/release-pypi.yml

@@ -1,10 +1,8 @@
 name: Release PyPI
 on:
   push:
-    branches:
-      - main
-    paths:
-      - "python/sglang/version.py"
+    tags:
+      - 'v[0-9]+.*'
   workflow_dispatch:
 
 jobs:
@@ -20,12 +18,14 @@ jobs:
 
       - name: Checkout repository
         uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for setuptools-scm to determine version from tags
 
       - name: Upload to pypi
         run: |
           cd python
           cp ../README.md ../LICENSE .
-          pip install build
+          pip install build wheel setuptools setuptools-scm
           python3 -m build
           pip install twine
           python3 -m twine upload dist/* -u __token__ -p ${{ secrets.PYPI_TOKEN }}

.github/workflows/release-tag.yml

@@ -1,35 +1,68 @@
 name: Release Tag
+# Creates a git tag to trigger release workflows (PyPI, Docker)
+# Use this after testing on a release branch is complete
 on:
-  push:
-    branches:
-      - main
-    paths:
-      - "python/sglang/version.py"
   workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to tag (without v prefix, e.g., 0.5.7)'
+        required: true
+        type: string
+      ref:
+        description: 'Branch or commit to tag (e.g., release/v0.5.7, main, or commit SHA)'
+        required: false
+        default: 'main'
+        type: string
 
 permissions:
   contents: write
 
 jobs:
-  publish:
+  create-tag:
     if: github.repository == 'sgl-project/sglang'
     runs-on: ubuntu-latest
     environment: 'prod'
     steps:
+      - name: Validate version format
+        run: |
+          VERSION="${{ github.event.inputs.version }}"
+          if [ -z "$VERSION" ]; then
+            echo "::error::Version is required"
+            exit 1
+          fi
+          if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+            echo "::error::Invalid version format: $VERSION (expected: X.Y.Z or X.Y.Z.postN)"
+            exit 1
+          fi
+          echo "Version validated: v$VERSION"
+
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
+          ref: ${{ github.event.inputs.ref }}
+          fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Get version
-        id: get_version
+      - name: Check if tag already exists
         run: |
-          version=$(cat python/sglang/version.py | cut -d'"' -f2)
-          echo "TAG=v$version" >> $GITHUB_OUTPUT
+          TAG="v${{ github.event.inputs.version }}"
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "::error::Tag $TAG already exists"
+            exit 1
+          fi
+          echo "Tag $TAG does not exist, proceeding..."
 
       - name: Create and push tag
         run: |
+          TAG="v${{ github.event.inputs.version }}"
+          REF="${{ github.event.inputs.ref }}"
+
           git config user.name "sglang-bot"
           git config user.email "sglang-bot@users.noreply.github.com"
-          git tag ${{ steps.get_version.outputs.TAG }}
-          git push origin ${{ steps.get_version.outputs.TAG }}
+
+          echo "Creating tag $TAG on ref $REF (commit: $(git rev-parse HEAD))"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+          echo "::notice::Successfully created and pushed tag $TAG"
+          echo "This will trigger the release workflows (PyPI, Docker)"