Organizational

Git & Commit Conventions

Standards for version control, conventional commits, and branching strategies.

Production

Commit Message Convention

We follow the Conventional Commits specification. This provides a structured history that allows for automated changelog generation and semantic versioning.

Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

You MUST use one of the following types:

Type	Description	When to use
feat	Feature	A new feature for the user, not a new feature for the build script.
fix	Bug Fix	A bug fix for the user.
chore	Chore	Changes to the build process or auxiliary tools and libraries such as documentation generation.
docs	Documentation	Documentation only changes.
style	Style	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
refactor	Refactoring	A code change that neither fixes a bug nor adds a feature.
perf	Performance	A code change that improves performance.
test	Tests	Adding missing tests or correcting existing tests.
ci	CI	Changes to our CI configuration files and scripts (e.g. GitHub Actions, Taskfile).
build	Build	Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
revert	Revert	Reverts a previous commit.

Scope (Optional)

The scope provides additional context:

feat(auth): add login support
fix(api): handle timeout in user service
chore(deps): upgrade react to v18

Description

Use the imperative, present tense: "change" not "changed" nor "changes".
Don't capitalize the first letter.
No dot (.) at the end.

Breaking Changes

Breaking changes MUST be indicated by:

A ! after the type/scope: feat(api)!: remove v1 endpoint
Or a BREAKING CHANGE: footer.

Only the final squashed commit merged into master must strictly follow the Conventional Commits specification.
Intermediate commits within a Pull Request may be less strict (e.g. WIP, fixup), as they will not land on master.

Pull Request Rules

Pull Requests should be small and focused on a single logical change.
The PR title will be used as the final squashed commit message and must follow Conventional Commits.
The PR description should clearly explain the why of the change, not only the what.
All CI checks (lint, tests) must pass before merging.
At least one approval is required before merging.

Branching Strategy

We use a simplified flow based on Feature Branches.

master: Production-ready code. Protected branch.
feature/*: For new features (e.g., feature/user-auth).
fix/*: For bug fixes (e.g., fix/login-error).
chore/*: For maintenance (e.g., chore/update-deps).

Workflow

Create a branch from master.
Commit changes using Conventional Commits.
Open a Pull Request (PR) to master.
Wait for CI checks (lint, test) to pass.
Get code review approval.
Squash and Merge into master.

Examples

Feature:

feat(search): add autocomplete to search bar

Adds a debounced search input that queries the autocomplete API
after 300ms of inactivity.

Bug Fix:

fix(payment): prevent double charge on retry

The payment button was not disabled after the first click,
allowing users to submit the form multiple times.

Breaking Change:

feat(auth)!: switch to JWT only

BREAKING CHANGE: The `session_id` cookie is no longer supported.
Clients must now send the `Authorization: Bearer <token>` header.

Chore:

chore(deps): update terraform to 1.5.0

Why This Matters

Automated Changelogs: We can generate release notes automatically based on feat and fix commits.
Semantic Versioning: We can determine if a release is Major, Minor, or Patch based on the commit types.
Readability: The history becomes easy to scan and understand.

ECR + GitHub Actions

Pattern for deploying container images using AWS ECR with OIDC authentication and per-project repository management.

GitHub Actions Workflows

Pattern for CI/CD workflow composition, authentication, and multi-environment deploy architecture.