fix: address RC2 vote feedback

.asf.yaml

@@ -63,7 +63,9 @@ github:
         # strict means "Require branches to be up to date before merging".
         strict: false
         # contexts are the names of checks that must pass
-        # contexts:
+        contexts:
+          - "Release Validation / build-artifacts"
+          - "Release Validation / install-and-smoke (3.12)"
       required_pull_request_reviews:
         dismiss_stale_reviews: false
         require_code_owner_reviews: false

.github/workflows/release-validation.yml

@@ -0,0 +1,174 @@
+#<!--
+#     Licensed to the Apache Software Foundation (ASF) under one
+#     or more contributor license agreements.  See the NOTICE file
+#     distributed with this work for additional information
+#     regarding copyright ownership.  The ASF licenses this file
+#     to you under the Apache License, Version 2.0 (the
+#     "License"); you may not use this file except in compliance
+#     with the License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#     Unless required by applicable law or agreed to in writing,
+#     software distributed under the License is distributed on an
+#     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#     KIND, either express or implied.  See the License for the
+#     specific language governing permissions and limitations
+#     under the License.
+#-->
+# Validates the Apache release pipeline on every PR: builds the real release
+# artifacts (git archive, sdist, wheel) using the release script with
+# --skip-signing, runs Apache RAT on the source tarball, then installs the
+# wheel into a fresh venv outside the source tree and smoke-tests the server.
+#
+# This is designed to catch the class of bugs that have broken recent RCs:
+# license/header issues (RAT), examples missing from the wheel (smoke test),
+# and general "voter tries to install this and it breaks" failures.
+
+name: Release Validation
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*.*.*-incubating-RC*'
+  pull_request:
+    types: [opened, synchronize, reopened]
+    paths-ignore:
+      - 'docs/**'
+      - 'website/**'
+      # Note: do NOT use '**/*.md' here. Some bundled examples ship .md files
+      # (e.g. examples/deployment/aws/terraform/tutorial.md) and a missing
+      # ASF header on those would cause a real RAT failure we want to catch.
+  workflow_dispatch:
+
+concurrency:
+  group: release-validation-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-artifacts:
+    name: build-artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          cache: pip
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: telemetry/ui/package-lock.json
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '17'
+
+      - name: Install system deps
+        run: sudo apt-get install -y --no-install-recommends graphviz
+
+      - name: Install Python build deps
+        run: pip install flit twine
+
+      - name: Cache Apache RAT
+        id: cache-rat
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/apache-rat
+          key: apache-rat-0.16.1
+
+      - name: Download Apache RAT if not cached
+        if: steps.cache-rat.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p ~/.cache/apache-rat
+          curl -fL -o ~/.cache/apache-rat/apache-rat-0.16.1.jar \
+            https://repo1.maven.org/maven2/org/apache/rat/apache-rat/0.16.1/apache-rat-0.16.1.jar
+
+      - name: Extract version
+        id: version
+        run: |
+          VERSION=$(python -c 'import re; print(re.search(r"version\s*=\s*\"([^\"]+)\"", open("pyproject.toml").read()).group(1))')
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "BURR_VERSION=$VERSION" >> "$GITHUB_ENV"
+
+      - name: Build release artifacts (no signing, no upload)
+        run: |
+          python scripts/apache_release.py all "$BURR_VERSION" 0 ci-runner \
+            --skip-signing --no-upload
+
+      - name: Verify all 3 artifacts exist
+        run: |
+          test -f "dist/apache-burr-${BURR_VERSION}-incubating-src.tar.gz"
+          test -f "dist/apache-burr-${BURR_VERSION}-incubating-sdist.tar.gz"
+          test -f "dist/apache_burr-${BURR_VERSION}-py3-none-any.whl"
+
+      - name: Run Apache RAT on source and sdist tarballs
+        run: |
+          python scripts/verify_apache_artifacts.py licenses \
+            --rat-jar ~/.cache/apache-rat/apache-rat-0.16.1.jar \
+            --artifacts-dir dist
+
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-artifacts
+          path: |
+            dist/*.tar.gz
+            dist/*.whl
+            dist/*.sha512
+            dist/rat-report-*.xml
+            dist/rat-report-*.txt
+          retention-days: 14
+
+  install-and-smoke:
+    name: install-and-smoke
+    needs: build-artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.9 is skipped because burr/cli/__main__.py uses PEP 604 union syntax
+        # (dict | None) which requires Python 3.10+. Tracked separately.
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-artifacts
+          path: dist
+
+      - name: Run smoke test
+        env:
+          BURR_VERSION: ${{ needs.build-artifacts.outputs.version }}
+        run: |
+          python scripts/ci_smoke_server.py \
+            --wheel "dist/apache_burr-${BURR_VERSION}-py3-none-any.whl"
+
+      - name: Upload smoke workspace on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: smoke-workspace-${{ matrix.python-version }}
+          path: /tmp/burr-smoke-*
+          retention-days: 7
+          if-no-files-found: ignore

.gitignore

@@ -201,3 +201,6 @@ examples/deployment/aws/terraform/*.tfstate
 examples/deployment/aws/terraform/*.tfstate.*
 examples/deployment/aws/terraform/.terraform.tfstate.lock.info
 examples/deployment/aws/terraform/*.tfplan
+
+# Claude Code session data
+.claude/

.rat-excludes

@@ -1,3 +1,12 @@
+# Apache RAT exclude patterns.
+#
+# IMPORTANT: RAT's -E flag matches each pattern as a regex, but only
+# reliably matches against the file basename. Path-style patterns like
+# 'examples/foo/bar.py' don't work, especially through symlinked dirs
+# (burr/examples is a symlink to ../examples in the source tree).
+# Use basename patterns. Be aware that broad basenames like 'utils.py'
+# will skip license checks on every utils.py in the repo.
+
 # Python marker file
 .*py\.typed
 
@@ -25,13 +34,45 @@ robots\.txt
 # JSON config files (cannot contain comments)
 .*\.json
 
-# Third-party MIT-licensed files (attributed in LICENSE)
-examples/deep-researcher/prompts\.py
-examples/deep-researcher/utils\.py
-website/src/components/ui/.*\.tsx
+# YAML config files in .github/ (templates with frontmatter, headers impractical)
+labeler\.yml
+config\.yml
+bug_report\.md
+feature_request\.md
+PULL_REQUEST_TEMPLATE\.md
+
+# Third-party MIT-licensed files (attributed in LICENSE).
+# Most names are unique within the repo so basename matching is safe.
+# Known collisions:
+#   - utils.py: also matches our own ASF code in burr/tracking/, etc.
+#     (4 other utils.py files; all currently have ASF headers)
+#   - button.tsx: also matches telemetry/ui/src/components/common/button.tsx
+#     (our own ASF code with header)
+# A future regression in any of those collision targets would silently pass
+# RAT. Tracked as a follow-up to rename or restructure.
+prompts\.py
+utils\.py
+animated-beam\.tsx
+animated-shiny-text\.tsx
+blur-fade\.tsx
+border-beam\.tsx
+button\.tsx
+dot-pattern\.tsx
+icon-cloud\.tsx
+magic-card\.tsx
+marquee\.tsx
+number-ticker\.tsx
+safari\.tsx
+shimmer-button\.tsx
+
+# Tutorial markdown for the AWS terraform deployment example
+tutorial\.md
 
 # SVG files (third-party logos and graphics, headers impractical)
 .*\.svg
 
-# Examples pattern (legacy - keeping for compatibility)
-apache_burr-.*/burr/examples
+# Image files (binary, cannot contain headers)
+.*\.png
+.*\.gif
+.*\.ico
+.*\.jpg

burr/cli/__main__.py

@@ -168,7 +168,7 @@ def _run_server(
     # TODO: Implement server running logic here
     # Example: Start a web server, configure ports, etc.
     logger.info(f"Starting server on port {port}")
-    cmd = f"uvicorn burr.tracking.server.run:app --port {port} --host {host}"
+    cmd = f"{sys.executable} -m uvicorn burr.tracking.server.run:app --port {port} --host {host}"
     if dev_mode:
         cmd += " --reload"
 

examples/deployment/aws/terraform/tutorial.md

@@ -1,3 +1,22 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
 # Apache Burr AWS Tracking Infrastructure Tutorial
 
 This tutorial explains how to deploy Apache Burr tracking infrastructure on AWS using Terraform. All Terraform code lives in `examples/deployment/aws/terraform/`. It covers deployment with S3 only (polling mode), with S3 and SQS (event-driven mode), and local development without AWS.

pyproject.toml

@@ -260,6 +260,7 @@ include = [
   "examples/multi-modal-chatbot/**",
   "examples/streaming-fastapi/**",
   "examples/deep-researcher/**",
+  "examples/hello-world-counter/**",
 ]
 exclude = [
   "telemetry/ui/node_modules/**",
@@ -290,7 +291,6 @@ exclude = [
   "examples/deployment/**",
   "examples/hamilton-integration/**",
   "examples/haystack-integration/**",
-  "examples/hello-world-counter/**",
   "examples/image-telephone/**",
   "examples/instructor-gemini-flash/**",
   "examples/integrations/**",