feat: add automatic version bump detection to bit ci merge (teambit#9838)

Enhances `bit ci merge` command with automatic version bump detection
from commit messages, eliminating the need to manually specify version
flags in many cases.

**Auto-detection priority:**
1. **Explicit keywords**: `BIT-BUMP-MAJOR`, `BIT-BUMP-MINOR` in commit
message
2. **Conventional commits**: `feat\!:`/`BREAKING CHANGE` → major,
`feat:` → minor, `fix:` → patch
3. **Default**: patch version bump

**Key features:**
- Only triggers when no explicit version flags (`--patch`, `--minor`,
`--major`) are provided
- Configurable via `useConventionalCommitsForVersionBump` and
`useExplicitBumpKeywords` in workspace.jsonc
- Includes CircleCI wrapper script for environment variable support
(`VERSION_BUMP_TYPE`)
- Comprehensive documentation with examples

Author: davidfirst

.circleci/config.yml

@@ -667,7 +667,7 @@ jobs:
       - run: bit config set user.token ${BIT_CLOUD_PROD_TOKEN}
       - run:
           name: 'bit ci merge'
-          command: 'cd bit && bit ci merge --build'
+          command: 'cd bit && bit ci merge --build ${BIT_CI_MERGE_EXTRA_FLAGS}'
           no_output_timeout: '50m'
           environment:
             NODE_OPTIONS: --max-old-space-size=32000

.gitignore

@@ -72,3 +72,6 @@ package-lock.json
 !.yarn/plugins
 !.yarn/sdks
 !.yarn/versions
+
+# Claude Code files
+.claude/

scopes/git/ci/ci.docs.mdx

@@ -96,6 +96,25 @@ bit ci merge [--message <string>] [--build] [--increment <level>] [--patch|--min
 | `--prerelease-id` |           | Prerelease identifier (e.g. "dev" to get "1.0.0-dev.1").                                                            |
 | `--increment-by`  |           | Increment by more than 1 (e.g. `--increment-by 2` with patch: 0.0.1 → 0.0.3).                                       |
 
+### Automatic Version Bump Detection
+
+When **no explicit version flags** are provided, `bit ci merge` can automatically determine the version bump level from the commit message:
+
+1. **Explicit Keywords** (highest priority):
+
+   - `BIT-BUMP-MAJOR` anywhere in commit message → major version bump
+   - `BIT-BUMP-MINOR` anywhere in commit message → minor version bump
+
+2. **Conventional Commits** (when enabled):
+
+   - `feat!:` or `BREAKING CHANGE` → major version bump
+   - `feat:` → minor version bump
+   - `fix:` → patch version bump
+
+3. **Default**: patch version bump
+
+**Note**: Auto-detection only occurs when no version flags (`--patch`, `--minor`, `--major`, etc.) are provided. Explicit flags always take precedence.
+
 ### Internal flow
 
 1. **Ensure main lane**
@@ -123,20 +142,34 @@ bit ci merge [--message <string>] [--build] [--increment <level>] [--patch|--min
 ### Version bump examples
 
 ```bash
-# Default patch increment (1.0.0 → 1.0.1)
-bit ci merge --message "fix: resolve memory leak"
-
-# Minor version bump (1.0.0 → 1.1.0)
+# Explicit version bump (takes precedence over auto-detection)
 bit ci merge --minor --message "feat: add new API endpoint"
-
-# Major version bump (1.0.0 → 2.0.0)
 bit ci merge --major --message "feat!: breaking API changes"
+bit ci merge --patch --increment-by 3 --message "fix: critical patches"
 
-# Prerelease increment (1.0.0 → 1.0.1-dev.1)
-bit ci merge --pre-release dev --message "feat: experimental feature"
+# Automatic detection from commit message (no flags needed)
+git commit -m "feat: add new API endpoint"
+bit ci merge --build  # → auto-detects minor bump
 
-# Custom increment amount (1.0.0 → 1.0.3)
-bit ci merge --patch --increment-by 3 --message "fix: critical patches"
+git commit -m "feat!: breaking API changes"
+bit ci merge --build  # → auto-detects major bump
+
+git commit -m "fix: resolve memory leak"
+bit ci merge --build  # → auto-detects patch bump (if conventional commits enabled)
+
+# Using explicit keywords for auto-detection
+git commit -m "feat: add new feature BIT-BUMP-MINOR"
+bit ci merge --build  # → auto-detects minor bump
+
+git commit -m "refactor: major code restructure BIT-BUMP-MAJOR"
+bit ci merge --build  # → auto-detects major bump
+
+# Default patch increment (when no detection rules match)
+git commit -m "chore: update dependencies"
+bit ci merge --build  # → defaults to patch bump
+
+# Prerelease increment (explicit flag required)
+bit ci merge --pre-release dev --message "feat: experimental feature"
 ```
 
 ### CI hint
@@ -152,7 +185,9 @@ The CI aspect supports configuration in `workspace.jsonc`:
 ```json
 {
   "teambit.git/ci": {
-    "commitMessageScript": "node scripts/generate-commit-message.js"
+    "commitMessageScript": "node scripts/generate-commit-message.js",
+    "useConventionalCommitsForVersionBump": true,
+    "useExplicitBumpKeywords": true
   }
 }
 ```
@@ -179,3 +214,45 @@ try {
   console.log('chore: update .bitmap and lockfiles as needed [skip ci]');
 }
 ```
+
+### `useConventionalCommitsForVersionBump`
+
+**Optional.** Enable automatic version bump detection based on conventional commit patterns.
+
+- **Default**: `false` (disabled)
+- **When enabled**: Analyzes commit messages for conventional commit patterns:
+  - `feat!:` or `BREAKING CHANGE` → major version bump
+  - `feat:` → minor version bump
+  - `fix:` → patch version bump
+
+```json
+{
+  "teambit.git/ci": {
+    "useConventionalCommitsForVersionBump": true
+  }
+}
+```
+
+### `useExplicitBumpKeywords`
+
+**Optional.** Enable automatic version bump detection using explicit keywords.
+
+- **Default**: `true` (enabled)
+- **Keywords**:
+  - `BIT-BUMP-MAJOR` anywhere in commit message → major version bump
+  - `BIT-BUMP-MINOR` anywhere in commit message → minor version bump
+
+```json
+{
+  "teambit.git/ci": {
+    "useExplicitBumpKeywords": false // disable explicit keywords
+  }
+}
+```
+
+**Example usage:**
+
+```bash
+git commit -m "feat: add new feature BIT-BUMP-MINOR"
+bit ci merge --build  # → automatically uses minor version bump
+```

scopes/git/ci/ci.main.runtime.ts

@@ -21,7 +21,64 @@ import { CiMergeCmd } from './commands/merge.cmd';
 import { git } from './git';
 
 export interface CiWorkspaceConfig {
+  /**
+   * Path to a custom script that generates commit messages for `bit ci merge` operations.
+   * The script will be executed when components are tagged and committed to the repository.
+   * If not specified, falls back to the default commit message:
+   * "chore: update .bitmap and lockfiles as needed [skip ci]"
+   *
+   * @example
+   * ```json
+   * {
+   *   "teambit.git/ci": {
+   *     "commitMessageScript": "node scripts/generate-commit-message.js"
+   *   }
+   * }
+   * ```
+   */
   commitMessageScript?: string;
+
+  /**
+   * Enables automatic version bump detection from conventional commit messages.
+   * When enabled, the system analyzes commit messages to determine the appropriate version bump:
+   * - `feat!:` or `BREAKING CHANGE` → major version bump
+   * - `feat:` → minor version bump
+   * - `fix:` → patch version bump
+   *
+   * Only applies when no explicit version flags (--patch, --minor, --major) are provided.
+   *
+   * @default false
+   * @example
+   * ```json
+   * {
+   *   "teambit.git/ci": {
+   *     "useConventionalCommitsForVersionBump": true
+   *   }
+   * }
+   * ```
+   */
+  useConventionalCommitsForVersionBump?: boolean;
+
+  /**
+   * Enables detection of explicit version bump keywords in commit messages.
+   * When enabled, the system looks for these keywords in commit messages:
+   * - `BIT-BUMP-MAJOR` → major version bump
+   * - `BIT-BUMP-MINOR` → minor version bump
+   *
+   * These keywords have higher priority than conventional commits parsing.
+   * Only applies when no explicit version flags are provided.
+   *
+   * @default true
+   * @example
+   * ```json
+   * {
+   *   "teambit.git/ci": {
+   *     "useExplicitBumpKeywords": true
+   *   }
+   * }
+   * ```
+   */
+  useExplicitBumpKeywords?: boolean;
 }
 
 export class CiMain {
@@ -139,6 +196,44 @@ export class CiMain {
     }
   }
 
+  private parseVersionBumpFromCommit(commitMessage: string): ReleaseType | null {
+    // Check explicit bump keywords (highest priority after env vars)
+    if (this.config.useExplicitBumpKeywords !== false) {
+      // default to true
+      if (commitMessage.includes('BIT-BUMP-MAJOR')) {
+        this.logger.console(chalk.blue('Found BIT-BUMP-MAJOR keyword in commit message'));
+        return 'major';
+      }
+      if (commitMessage.includes('BIT-BUMP-MINOR')) {
+        this.logger.console(chalk.blue('Found BIT-BUMP-MINOR keyword in commit message'));
+        return 'minor';
+      }
+    }
+
+    // Check conventional commits if enabled
+    if (this.config.useConventionalCommitsForVersionBump) {
+      // Check for breaking changes (major version bump)
+      if (/^feat!(\(.+\))?:|^fix!(\(.+\))?:|BREAKING CHANGE/m.test(commitMessage)) {
+        this.logger.console(chalk.blue('Found breaking changes in commit message (conventional commits)'));
+        return 'major';
+      }
+
+      // Check for features (minor version bump)
+      if (/^feat(\(.+\))?:/m.test(commitMessage)) {
+        this.logger.console(chalk.blue('Found feature commits (conventional commits)'));
+        return 'minor';
+      }
+
+      // Check for fixes (patch version bump) - explicit patch not needed as it's default
+      if (/^fix(\(.+\))?:/m.test(commitMessage)) {
+        this.logger.console(chalk.blue('Found fix commits (conventional commits) - using default patch'));
+        return 'patch';
+      }
+    }
+
+    return null; // No specific version bump detected
+  }
+
   private async getCustomCommitMessage() {
     try {
       const commitMessageScript = this.config.commitMessageScript;
@@ -359,21 +454,22 @@ export class CiMain {
     releaseType,
     preReleaseId,
     incrementBy,
+    explicitVersionBump,
   }: {
     message?: string;
     build?: boolean;
     strict?: boolean;
-    releaseType?: ReleaseType;
+    releaseType: ReleaseType;
     preReleaseId?: string;
     incrementBy?: number;
+    explicitVersionBump?: boolean;
   }) {
     const message = argMessage || (await this.getGitCommitMessage());
     if (!message) {
       throw new Error('Failed to get commit message from git. Please provide a message using --message option.');
     }
 
     const currentLane = await this.lanes.getCurrentLane();
-
     if (currentLane) {
       // this doesn't normally happen. we expect this mergePr to be called from the default branch, which normally checks
       // out to main lane.
@@ -425,13 +521,14 @@ export class CiMain {
 
     this.logger.console('📦 Component Operations');
     this.logger.console(chalk.blue('Tagging components'));
+    const finalReleaseType = await this.determineReleaseType(releaseType, explicitVersionBump);
     const tagResults = await this.snapping.tag({
       all: true,
       message,
       build,
       failFast: true,
       persist: hasSoftTaggedComponents,
-      releaseType,
+      releaseType: finalReleaseType,
       preReleaseId,
       incrementBy,
     });
@@ -490,6 +587,29 @@ export class CiMain {
 
     return { code: 0, data: '' };
   }
+
+  /**
+   * Auto-detect version bump from commit messages if no explicit version bump was provided
+   */
+  private async determineReleaseType(releaseType: ReleaseType, explicitVersionBump?: boolean): Promise<ReleaseType> {
+    if (explicitVersionBump) {
+      this.logger.console(chalk.blue(`Using explicit version bump: ${releaseType}`));
+      return releaseType;
+    }
+    // Only auto-detect if user didn't specify any version flags
+    const lastCommit = await this.getGitCommitMessage();
+    if (!lastCommit) {
+      this.logger.console(chalk.blue('No commit message found, using default patch'));
+      return releaseType;
+    }
+    const detectedReleaseType = this.parseVersionBumpFromCommit(lastCommit);
+    if (detectedReleaseType) {
+      this.logger.console(chalk.green(`Auto-detected version bump: ${detectedReleaseType}`));
+      return detectedReleaseType;
+    }
+    this.logger.console(chalk.blue('No specific version bump detected, using default patch'));
+    return releaseType;
+  }
 }
 
 // @ts-ignore

scopes/git/ci/commands/merge.cmd.ts

@@ -57,13 +57,19 @@ export class CiMergeCmd implements Command {
 
     const { releaseType, preReleaseId } = validateOptions(options);
 
+    // Check if user explicitly provided any version bump flags
+    const explicitVersionBump = Boolean(
+      options.increment || options.patch || options.minor || options.major || options.preRelease
+    );
+
     return this.ci.mergePr({
       message: options.message,
       build: options.build,
       strict: options.strict,
       releaseType,
       preReleaseId,
       incrementBy: options.incrementBy,
+      explicitVersionBump,
     });
   }
 }