yaba-release-cli/docs/releases/2.2.0.md

Yaba is a simple CLI tool that helps you manage releases of your Github projects.

# Yaba 2.2.0 Release Plan

## Target

- Package: `yaba-release-cli`
- Version: `2.2.0`
- Release type: minor
- Date prepared: `2026-03-15`

## Scope

`2.2.0` is a minor release that adds configurable release notes grouping, comprehensive configuration documentation, and CI workflow improvements.

## Included Changes

### Core Feature: Configurable Label Buckets
- New optional `release.labelBuckets` field in `yaba.config.json`
- Teams can customize PR-label-to-section mappings for GitHub release notes
- Default buckets still used when config is absent (fully backward compatible)
- Dynamic grouping engine supports custom bucket count and order
- Automatic "Internal" catch-all bucket for unmatched PRs
- Optional `title` field with automatic camelCase-to-title-case derivation

### Configuration & Validation
- New `validateLabelBuckets()` function in config validation service
- Comprehensive schema validation for labelBuckets structure
- Config errors caught early with descriptive messages
- Support for custom bucket definitions across all release workflows

### Documentation
- New `CONFIG.md`: Complete configuration reference guide
- New `yaba.config.example.json`: Full working example with all options
- Updated `README.md`: Feature explanation and usage example
- Updated `website/index.html`: Marketing copy reflects new capability

### CI/CD Improvements
- New config validation step in release workflow (`yaba config validate`)
- Validation runs before release creation, fails early on config errors
- Improved GitHub Actions step names for clarity and consistency
- Human-readable validation output in workflow logs

## Technical Details

### Implementation Changes
- `bin/services/release-notes-service.js`: Dynamic bucketing engine
  - Renamed `labelBuckets` → `DEFAULT_LABEL_BUCKETS` with explicit titles
  - Accept `labelBuckets` parameter in `buildReleaseNotesBundle()`
  - New `resolveSectionTitle()` helper for title derivation
  - Updated `renderHighlights()` and `buildShippedFromPullRequests()` for dynamic buckets

- `bin/services/runtime-config-service.js`: Config integration
  - Add `labelBuckets: null` to default template
  - Resolve `labelBuckets` in `releaseContext`

- `bin/services/config-validation-service.js`: Schema validation
  - New `validateLabelBuckets()` function with comprehensive checks
  - Validate bucket structure, key uniqueness, label arrays

- `bin/commands/release-command.js`: Data threading
  - Pass `labelBuckets` to both `buildReleaseNotesBundle()` call sites

- `bin/assets/github-release-template.md`: Template simplification
  - Replace 6 fixed section placeholders with single `{sections}` placeholder

- `bin/utils/template-utils.js`: Updated signature
  - Change `generateGroupedGithubReleaseNotes()` to accept pre-rendered sections

- `.github/workflows/release.yml`: CI improvements
  - Add config validation step before release creation
  - Improved step naming for consistency

## Compatibility

- **Fully backward compatible**: When `labelBuckets` is null or absent, uses `DEFAULT_LABEL_BUCKETS`
- No breaking CLI contract changes
- Existing configurations continue to work unchanged
- All 74 existing tests pass without modification

## Configuration Example

```json
{
  "release": {
    "labelBuckets": [
      {
        "key": "security",
        "title": "Security Fixes",
        "labels": ["security", "type:security"]
      },
      {
        "key": "chore",
        "title": "Chore",
        "labels": ["chore", "type:chore"]
      }
    ]
  }
}
```

## Release Checklist

1. Validate locally:
   - `npm ci`
   - `npm test` (all 74 tests pass)
   - `yaba config validate`
   - `node --check bin/index.js`

2. Confirm version metadata:
   - `package.json` is `2.2.0`
   - `package-lock.json` is `2.2.0`

3. Merge all feature PRs:
   - `feat/configurable-label-buckets` (core feature)
   - `docs/configurable-label-buckets-guide` (documentation)
   - `ci/add-config-validation-to-release-workflow` (workflow improvements)
   - `chore/bump-version-to-2.2.0` (version bump)

4. Tag and publish:
   - tag `v2.2.0`
   - trigger `Release with Yaba` workflow with:
     - `release-descriptor`: `Release v2.2.0`
     - `tag-name`: `v2.2.0`

5. Post-release smoke tests:
   - `npm view yaba-release-cli version` shows `2.2.0`
   - `npm i -g yaba-release-cli@2.2.0`
   - `yaba --version` shows `2.2.0`
   - `yaba doctor --format json` succeeds
   - `yaba config validate` with custom labelBuckets succeeds
   - `yaba release preview --repo yaba` shows custom grouping (if config present)

## Notable Features in 2.2.0

✅ Customizable release notes grouping
✅ Comprehensive configuration documentation
✅ Schema validation for custom configurations
✅ CI workflow improvements and fail-fast validation
✅ Fully backward compatible with existing workflows
✅ Zero breaking changes to CLI contract