apache · adityamparikh · Jan 6, 2026
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
@@ -0,0 +1,123 @@
+# 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.
+
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║                         RELEASE PLEASE WORKFLOW                            ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+#
+# PURPOSE:
+# --------
+# Automates releases using Google's release-please tool. This workflow:
+# - Generates and maintains CHANGELOG.md from conventional commits
+# - Automatically bumps versions based on commit types
+# - Creates Release PRs that can be reviewed before releasing
+# - Creates GitHub Releases when the Release PR is merged
+#
+# HOW IT WORKS:
+# -------------
+# 1. On every push to main, release-please analyzes new commits
+# 2. If there are releasable changes, it creates/updates a "Release PR"
+# 3. The Release PR contains:
+#    - Updated CHANGELOG.md with all changes since last release
+#    - Version bump in tracked files (if configured)
+#    - Release notes preview
+# 4. When the Release PR is merged:
+#    - A GitHub Release is created with the changelog
+#    - A git tag is created (e.g., v1.0.0)
+#
+# VERSION BUMPING:
+# ----------------
+# Based on Conventional Commits (https://www.conventionalcommits.org/):
+# - fix: → patch version bump (1.0.0 → 1.0.1)
+# - feat: → minor version bump (1.0.0 → 1.1.0)
+# - feat!: or BREAKING CHANGE → major version bump (1.0.0 → 2.0.0)
+#
+# COMMIT TYPES INCLUDED IN CHANGELOG:
+# -----------------------------------
+# - feat: New features
+# - fix: Bug fixes
+# - perf: Performance improvements
+# - revert: Reverted changes
+# - docs: Documentation (optional, configurable)
+# - chore, style, refactor, test, build, ci: Excluded by default
+#
+# WHEN IT TRIGGERS:
+# -----------------
+# - Automatically on every push to main branch
+# - Creates/updates Release PR with pending changes
+# - No manual trigger needed
+#
+# REQUIREMENTS:
+# -------------
+# - Conventional commit messages (feat:, fix:, etc.)
+# - GITHUB_TOKEN with contents:write and pull-requests:write
+#
+# EXAMPLE WORKFLOW:
+# -----------------
+# 1. Merge PRs with conventional commits to main
+#    - "feat: add new search filter"
+#    - "fix: handle null values in indexing"
+#
+# 2. Release-please automatically creates/updates PR titled:
+#    "chore(main): release 1.1.0"
+#
+# 3. Review the Release PR (check CHANGELOG.md looks correct)
+#
+# 4. Merge the Release PR when ready to release
+#    - GitHub Release is created automatically
+#    - Tag v1.1.0 is created
+#
+# RELATED DOCUMENTATION:
+# ----------------------
+# - release-please: https://github.com/googleapis/release-please
+# - Conventional Commits: https://www.conventionalcommits.org/
+# - dev-docs/WORKFLOWS.md: Documentation for all workflows
+
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      # ┌───────────────────────────────────────────────────────────────────────┐
+      # │ Release Please Action                                                 │
+      # │                                                                        │
+      # │ This action handles everything automatically:                         │
+      # │ 1. Analyzes commits since last release                                │
+      # │ 2. Determines version bump (major/minor/patch)                        │
+      # │ 3. Generates CHANGELOG.md entries                                     │
+      # │ 4. Creates/updates Release PR                                         │
+      # │ 5. Creates GitHub Release when PR is merged                           │
+      # │                                                                        │
+      # │ release-type: simple                                                  │
+      # │   - Works with any project type                                       │
+      # │   - Manages CHANGELOG.md and version tracking                         │
+      # │   - Does not modify build files (use 'java' for pom.xml updates)     │
+      # └───────────────────────────────────────────────────────────────────────┘
+      - uses: googleapis/release-please-action@v4
+        with:
+          # Release type determines how versions are tracked
+          # 'simple' works for any project and manages CHANGELOG.md
+          # Other options: java, node, python, etc. (update build files)
+          release-type: simple
diff --git a/dev-docs/WORKFLOWS.md b/dev-docs/WORKFLOWS.md
@@ -9,6 +9,7 @@ This guide explains when and how to use each GitHub Actions workflow in the proj
 | [build-and-publish.yml](#build-and-publishyml) | Development CI/CD     | Automatic (push/PR)  | ✅ Active   | Daily development      |
 | [release-publish.yml](#release-publishyml)     | Official ASF releases | Manual (after vote)  | ✅ Active   | Production releases    |
 | [nightly-build.yml](#nightly-buildyml)         | Nightly builds        | Scheduled (2 AM UTC) | ✅ Active   | Latest unstable builds |
+| [release-please.yml](#release-pleaseyml)       | Automated releases    | Automatic (push)     | ✅ Active   | Changelog & releases   |
 | [atr-release-test.yml](#atr-release-testyml)   | ATR testing           | Manual (safe mode)   | ✅ Ready    | Testing ATR workflow   |
 | [atr-release.yml](#atr-releaseyml)             | ATR production        | Manual (blocked)     | ⚠️ Blocked | Future ATR releases    |
 
@@ -324,6 +325,95 @@ docker pull apache/solr-mcp-nightly:nightly-20250112-a1b2c3d
 
 ---
 
+### release-please.yml
+
+**Purpose**: Automate releases, changelog generation, and version bumping using Google's release-please
+
+#### When to Use
+
+- ✅ Automatically runs on every push to main
+- ✅ Creates Release PRs with changelog updates
+- ✅ Automatically bumps versions based on commits
+- ✅ Creates GitHub Releases when Release PR is merged
+
+#### When NOT to Use
+
+- ❌ If not using conventional commit messages
+- ❌ For ASF official releases (use `release-publish.yml` after vote)
+
+#### Triggers
+
+```yaml
+on:
+  push:
+    branches:
+      - main  # Runs on every push to main
+```
+
+#### What It Does
+
+1. **Analyzes** commits since the last release
+2. **Determines** version bump based on commit types:
+   - `fix:` → patch (1.0.0 → 1.0.1)
+   - `feat:` → minor (1.0.0 → 1.1.0)
+   - `feat!:` or `BREAKING CHANGE` → major (1.0.0 → 2.0.0)
+3. **Creates/updates** a Release PR with:
+   - Updated CHANGELOG.md
+   - Version bump
+   - Release notes preview
+4. **Creates GitHub Release** when Release PR is merged
+
+#### How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 1. Push commits to main                                         │
+│    feat: add new search filter                                  │
+│    fix: handle null values                                      │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 2. Release-please creates/updates PR                            │
+│    Title: "chore(main): release 1.1.0"                          │
+│    Contains: CHANGELOG.md updates, version bump                 │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 3. Review and merge Release PR when ready                       │
+└─────────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────────┐
+│ 4. GitHub Release created automatically                         │
+│    - Tag: v1.1.0                                                │
+│    - Release notes from CHANGELOG.md                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+#### Example Workflow
+
+```bash
+# 1. Merge PRs with conventional commits
+git commit -m "feat: add fuzzy search support"
+git commit -m "fix: handle empty query strings"
+git push origin main
+
+# 2. Release-please automatically creates PR:
+#    "chore(main): release 1.2.0"
+
+# 3. Review the PR, check CHANGELOG.md
+
+# 4. Merge the PR → GitHub Release is created
+```
+
+#### Example Use Cases
+
+- Automating changelog generation on every merge
+- Consistent version bumping based on commit types
+- Creating GitHub Releases with proper release notes
+- Reducing manual release overhead
+
+---
+
 ### atr-release-test.yml
 
 **Purpose**: Test Apache Trusted Releases (ATR) workflow safely
@@ -493,16 +583,18 @@ gh workflow run atr-release.yml \
 
 ## Workflow Comparison Matrix
 
-| Feature              | build-and-publish | release-publish | nightly-build      | atr-release-test | atr-release |
-|----------------------|-------------------|-----------------|--------------------|------------------|-------------|
-| **Status**           | ✅ Active          | ✅ Active        | ✅ Active           | ✅ Ready          | ⚠️ Blocked  |
-| **Trigger**          | Automatic         | Manual          | Scheduled          | Manual           | Manual      |
-| **Docker Namespace** | Personal/GHCR     | `apache/*`      | `apache/*-nightly` | Test             | `apache/*`  |
-| **MCP Registry**     | ❌ No              | ✅ Yes           | ❌ No               | ❌ No             | ✅ Yes       |
-| **ASF Vote**         | ❌ Not required    | ✅ Required      | ❌ Not required     | ❌ Not required   | ✅ Required  |
-| **Signing**          | ❌ No              | ⚠️ Manual       | ❌ No               | ⚠️ Simulated     | ✅ Automated |
-| **Production Ready** | ❌ No              | ✅ Yes           | ❌ No               | ❌ No             | ⚠️ Future   |
-| **Can Test Now**     | ✅ Yes             | ✅ Yes           | ✅ Yes              | ✅ Yes            | ❌ No        |
+| Feature              | build-and-publish | release-publish | nightly-build      | release-please | atr-release-test | atr-release |
+|----------------------|-------------------|-----------------|--------------------|----------------|------------------|-------------|
+| **Status**           | ✅ Active          | ✅ Active        | ✅ Active           | ✅ Active       | ✅ Ready          | ⚠️ Blocked  |
+| **Trigger**          | Automatic         | Manual          | Scheduled          | Automatic      | Manual           | Manual      |
+| **Docker Namespace** | Personal/GHCR     | `apache/*`      | `apache/*-nightly` | N/A            | Test             | `apache/*`  |
+| **MCP Registry**     | ❌ No              | ✅ Yes           | ❌ No               | ❌ No           | ❌ No             | ✅ Yes       |
+| **ASF Vote**         | ❌ Not required    | ✅ Required      | ❌ Not required     | ❌ Not required | ❌ Not required   | ✅ Required  |
+| **Signing**          | ❌ No              | ⚠️ Manual       | ❌ No               | ❌ No           | ⚠️ Simulated     | ✅ Automated |
+| **Production Ready** | ❌ No              | ✅ Yes           | ❌ No               | ✅ Yes          | ❌ No             | ⚠️ Future   |
+| **Version Bump**     | ❌ No              | ❌ No            | ❌ No               | ✅ Automatic    | ❌ No             | ❌ No        |
+| **GitHub Release**   | ❌ No              | ✅ Yes           | ✅ Pre-release      | ✅ Automatic    | ❌ No             | ✅ Yes       |
+| **Can Test Now**     | ✅ Yes             | ✅ Yes           | ✅ Yes              | ✅ Yes        | ✅ Yes            | ❌ No        |
 
 ---