Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

chore: conventionalcommits enforment (#869)

Hector Venturaa1d3c82dfa48
diff --git a/.github/workflows/conventional-commits.yml b/.github/workflows/conventional-commits.yml
new file mode 100644
index 0000000000..2994d82f1e
--- /dev/null
+++ b/.github/workflows/conventional-commits.yml
@@ -0,0 +1,51 @@
+name: Conventional Commits
+
+on:
+ pull_request:
+ types: [opened, edited, synchronize, reopened]
+
+permissions:
+ pull-requests: read
+
+jobs:
+ lint-pr-title:
+ name: PR title follows Conventional Commits
+ runs-on: ubuntu-latest
+ steps:
+ - name: Validate PR title
+ env:
+ PR_TITLE: ${{ github.event.pull_request.title }}
+ run: |
+ # Conventional Commits pattern:
+ # <type>[optional scope]: <description>
+ #
+ # Types recognised by semantic-release (commit-analyzer defaults):
+ # feat, fix, perf, revert, docs, style, chore, refactor, test, build, ci
+ #
+ # Breaking changes are signalled by appending ! before the colon:
+ # feat!: or feat(scope)!:
+ #
+ # References:
+ # https://www.conventionalcommits.org/en/v1.0.0/
+ # https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular
+
+ PATTERN='^(feat|fix|perf|revert|docs|style|chore|refactor|test|build|ci)(\([a-zA-Z0-9_\-\.]+\))?!?: .{1,}'
+
+ if echo "$PR_TITLE" | grep -qE "$PATTERN"; then
+ echo "PR title is valid: $PR_TITLE"
+ else
+ echo "::error::PR title does not follow Conventional Commits."
+ echo ""
+ echo " Got: $PR_TITLE"
+ echo ""
+ echo " Expected format: <type>[optional scope]: <description>"
+ echo " Examples:"
+ echo " feat(dynamodb): add PartiQL ExecuteStatement support"
+ echo " fix(s3): make us-east-1 bucket creation idempotent"
+ echo " chore: release 1.5.16"
+ echo " feat!: remove legacy endpoint"
+ echo ""
+ echo " Valid types: feat, fix, perf, revert, docs, style, chore, refactor, test, build, ci"
+ echo " See: https://www.conventionalcommits.org/en/v1.0.0/"
+ exit 1
+ fi
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ec50ae3500..53cc23b978 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -59,25 +59,66 @@ Floci uses a **tag-driven release model**. Docker images are never published on
This project uses [Conventional Commits](https://www.conventionalcommits.org/) — semantic-release reads these to generate the changelog and version bumps automatically.
-| Prefix | When to use | Version bump |
-|--------|-------------|--------------|
-| `feat:` | New AWS API action or service | minor |
-| `fix:` | Bug fix or AWS compatibility correction | patch |
-| `perf:` | Performance improvement | patch |
-| `docs:` | Documentation only | none |
-| `chore:` | Build, CI, dependencies | none |
-| `BREAKING CHANGE:` | Footer or `!` suffix — incompatible change | major |
+> **The PR title is validated automatically by CI** and must follow this format, since it becomes the squash-merge commit message that semantic-release reads.
-Do not include `Co-Authored-By` trailers for AI tools in commit messages. Attribution should be limited to human contributors.
+### Format
+
+```
+<type>[optional scope]: <description>
+```
+
+- **type** — one of the values in the table below (lowercase)
+- **scope** — optional, in parentheses, identifies the service or area (e.g. `s3`, `dynamodb`, `core`)
+- **description** — short summary in the imperative mood, no trailing period
+- Append `!` before the colon to signal a breaking change: `feat(api)!:`
+
+| Type | When to use | Version bump |
+|------|-------------|--------------|
+| `feat` | New AWS API action or service | minor |
+| `fix` | Bug fix or AWS compatibility correction | patch |
+| `perf` | Performance improvement | patch |
+| `revert` | Reverts a previous commit | patch |
+| `docs` | Documentation only | none |
+| `style` | Formatting, whitespace — no logic change | none |
+| `chore` | Build, CI, dependencies, housekeeping | none |
+| `refactor` | Code restructure without behavior change | none |
+| `test` | Adding or updating tests | none |
+| `build` | Build system or tooling changes | none |
+| `ci` | CI workflow changes | none |
+| `BREAKING CHANGE` | Footer or `!` suffix — incompatible change | major |
+
+### Valid examples ✅
-**Examples:**
+```
+feat(dynamodb): add PartiQL ExecuteStatement support
+fix(s3): make us-east-1 bucket creation idempotent
+perf(kinesis): reduce lock contention in shard iterator
+chore: release 1.5.16
+docs: update README with new configuration options
+refactor(sqs): extract message visibility logic
+test(kms): add encrypt/decrypt round-trip test
+feat!: remove legacy v1 endpoint
+fix(dynamodb)!: correct TransactWriteItems error shape
+ci: add conventional commits lint workflow
+build: bump Quarkus to 3.32.3
+```
+
+### Invalid examples ❌
```
-feat: add SQS SendMessageBatch action
-fix: correct DynamoDB QueryFilter comparison operators
-feat!: change default storage mode to persistent
+Add PartiQL support # missing type
+Feature: add something # "Feature" is not a valid type
+feat : space before colon # space before colon
+feat(dynamodb)add missing colon # missing colon
+FIX(s3): uppercase type # type must be lowercase
+feat(my scope): scope has spaces # scope cannot contain spaces
+fix(): empty scope # empty scope
+feat(s3):no space after colon # missing space after colon
+wip: still working on this # "wip" is not a recognised type
```
+Do not include `Co-Authored-By` trailers for AI tools in commit messages. Attribution should be limited to human contributors.
+
## Architecture
See [AGENT.md](AGENT.md) for a detailed description of the three-layer architecture (Controller → Service → Storage), the AWS wire protocol mapping, and conventions for adding new services.
diff --git a/docs/contributing.md b/docs/contributing.md
index 71413889ed..42ee055bba 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -30,15 +30,50 @@ mvn test -Dtest=SsmIntegrationTest#putParameter
This project uses [Conventional Commits](https://www.conventionalcommits.org/) — required for semantic-release to generate the changelog and version bumps automatically.
-| Prefix | Effect |
+> **The PR title is validated automatically by CI** and must follow this format, since it becomes the squash-merge commit message that semantic-release reads.
+
+### Format
+
+```
+<type>[optional scope]: <description>
+```
+
+| Type | Effect |
|---|---|
-| `feat:` | New feature → minor version bump |
-| `fix:` | Bug fix → patch version bump |
-| `perf:` | Performance improvement → patch |
-| `docs:` | Documentation only → no version bump |
-| `chore:` | Build/CI → no version bump |
+| `feat` | New feature → minor version bump |
+| `fix` | Bug fix → patch version bump |
+| `perf` | Performance improvement → patch |
+| `revert` | Reverts a previous commit → patch |
+| `docs` | Documentation only → no version bump |
+| `style` | Formatting, whitespace → no version bump |
+| `chore` | Build/CI/housekeeping → no version bump |
+| `refactor` | Code restructure → no version bump |
+| `test` | Adding/updating tests → no version bump |
+| `build` | Build system changes → no version bump |
+| `ci` | CI workflow changes → no version bump |
| `feat!:` or `BREAKING CHANGE:` | Breaking change → major bump |
+### Valid examples ✅
+
+```
+feat(dynamodb): add PartiQL ExecuteStatement support
+fix(s3): make us-east-1 bucket creation idempotent
+chore: release 1.5.16
+feat!: remove legacy v1 endpoint
+ci: add conventional commits lint workflow
+```
+
+### Invalid examples ❌
+
+```
+Add PartiQL support # missing type
+Feature: add something # not a valid type
+feat : space before colon # space before colon
+FIX(s3): uppercase type # type must be lowercase
+feat(my scope): spaces in scope # scope cannot contain spaces
+wip: still working on this # not a recognised type
+```
+
## Adding a New AWS Service
See [AGENT.md](https://github.com/floci-io/floci/blob/main/AGENT.md) for the full architecture guide. `AGENT.md` is the canonical agent instructions file for this repository. If your coding agent expects a different filename, create a local symlink to `AGENT.md` instead of copying it.