# Commit Syntax

This repo uses `standard-version` for release commits, version tags, and changelog generation.

For useful release notes, commit messages should follow Conventional Commits while still keeping the GitHub issue/ticket number near the front.

## Recommended Format

```text
<type>: <ticket number> <description>
```

Examples:

```text
feat: 123 add ASTextField theme override helper
fix: 124 correct ASChoiceBar large button spacing
chore: 125 document release process
chore: 126 update dependencies
chore: 127 simplify ASTextField value ownership
```

This format is parser-friendly for `standard-version` and still keeps the ticket number easy to scan.

## Branches and review

Ticket branches use `<ticket-number>-<branch-description>`, for example `94-donut-theme-migration`. Check the current branch and working tree before editing, and confirm the intended target when unclear.

Wait for Andrey's review and explicit readiness signal before the initial commit. Stage intended files and inspect the staged diff before committing. Report the commit hash and summary afterward. Never push unless explicitly asked; PR creation, review requests, merging, and publishing remain with Andrey unless delegated.

## Commit body / PR description

Give the initial commit a Markdown body suitable for reuse as the PR description. Describe the concrete problem and resulting behavior, relevant API/theme/documentation changes, and validation actually performed. For example:

```markdown
Allow consumers to customize the component's focus appearance through its theme.

- Add a semantic focus slot while preserving the classic default.
- Document the property, preset defaults, and usage in the component guide.

Validation: library TypeScript check and relevant theme regression tests passed.
```

Adapt the body to the actual change and checks. Follow-up commits addressing requested Copilot review may have a brief or omitted body when the review already explains the change. See [Component development workflow](./component-workflow.md#commits-pull-requests-and-tracking-tickets) for overarching ticket updates and completed PR links.

## Types

Use an appropriate prefix from `major`, `feat`, `feature`, `fix`, `bugfix`, `patch`, or `chore`, following Andrey's commit convention. Prefer `feat` for new capabilities, `fix` for bug fixes, and `chore` for maintenance or documentation so the existing release tooling can classify them predictably. Do not assume aliases such as `feature`, `bugfix`, `patch`, or `major` infer a release bump; use the supported breaking-change notation or an explicit release version when appropriate.

## Version Bump Behavior

`standard-version` looks at commits since the last tag and infers the next version:

```text
fix: ...      -> patch bump
feat: ...     -> minor bump
BREAKING CHANGE or ! -> major bump
```

Examples from `2.13.4`:

```text
fix: 128 correct ASTextField clear button behavior
```

would normally produce:

```text
2.13.5
```

```text
feat: 128 add theme override helper
```

would normally produce:

```text
2.14.0
```

```text
feat!: 128 replace textfield theme API
```

would normally produce:

```text
3.0.0
```

## Breaking Changes

Use `!` after the type/scope:

```text
feat!: 128 replace textfield theme API
```

Or include a footer:

```text
feat: 128 replace textfield theme API

BREAKING CHANGE: textfield theme keys were renamed.
```

## Manual Version Control

The inferred version can be overridden:

```bash
npm run release -- --release-as patch
npm run release -- --release-as minor
npm run release -- --release-as major
npm run release -- --release-as 2.14.3
```

## Release Flow

Run releases from a clean, up-to-date `main` branch after feature work has been merged.

Release commands are for Andrey or an explicitly delegated release task; this guide is not authorization to commit, push, or publish. The intended release flow is:

```bash
npm run release
git push --follow-tags origin main
```

`npm run release` runs `standard-version`, which:

1. reads commits since the last tag
2. updates `package.json`
3. updates `package-lock.json`
4. updates `CHANGELOG.md`
5. creates a release commit
6. creates a version tag such as `v2.13.5`

Pushing the tag triggers the publish workflow.

## Avoid

Avoid ticket-first messages when you want automatic changelog generation:

```text
#123 Added ASTextField theme override helper
```

This is readable for humans, but `standard-version` will not classify it as a feature or fix.

Prefer:

```text
feat: 123 add ASTextField theme override helper
```