adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 18:33:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
engineering-handbook/confluence/02-git-workflow.md
Claude 735b407017
docs(confluence): add sanitized standards export for partner teams 
Partner engineering teams need the standards without access to this
repo, which contains internal repo names, account identifiers, and
migration history. Adds eight simplified pages, one per Confluence
page, plus an internal README with source mapping and exclusions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UP6j3hYgoVqjKZwC3XB9ay
2026-09-27 01:58:05 +00:00

3 KiB
Raw Blame History

Git Workflow

Branches

Never commit directly to main. Create a branch using one of these prefixes plus a kebab-case description:

Prefix Use when
feature/ Adding or enhancing functionality
fix/ Fixing a defect before it reaches production
hotfix/ Fixing a production issue that needs immediate attention
chore/ Maintenance, cleanup, dependency bumps, tooling
docs/ Documentation-only changes
refactor/ Restructuring code without changing behavior
release/ Preparing a release

Example: feature/add-receipt-parser.

Do not put the Jira key in the branch name. It goes in the PR title (see Pull Requests and Code Review).

Delete your branch after it merges.

Commits

Commit each logical change on its own. We use Conventional Commits:

type(scope): description
  • type (required): one of the types below
  • scope (optional): the area affected, lowercase, such as auth, api, or deps
  • description (required): imperative mood, lowercase, no trailing period
Type Use for
feat A new feature
fix A bug fix
docs Documentation only
style Formatting with no behavior change
refactor Code change that is neither a fix nor a feature
perf Performance improvement
test Adding or correcting tests
build Build system or dependency changes
ci CI/CD configuration
chore Routine maintenance
revert Reverting a previous commit
release Cutting a release

Commit message rules

  • Keep the header under 72 characters.
  • Write what the commit does: add retry logic, not added retry logic.
  • Use the body to explain why. The diff already shows what.
  • No vague messages: fix: stuff, chore: update code, and chore: address review comments are not acceptable.
  • No WIP commits on shared branches.

Mark breaking changes with ! and a BREAKING CHANGE: footer:

feat(api)!: remove the deprecated /v1/receipts endpoint

BREAKING CHANGE: clients must migrate to /v2/receipts.

Optionally reference the Jira ticket in a trailer:

feat(payments): add retry logic for transient upstream failures

The payment processor returns 503 during its deployments. Without
retries these surface as user-facing errors. This adds exponential
backoff with 3 attempts.

Refs: DEV-123

Push rules

  • Push regularly. Do not sit on unpushed work.
  • Never force-push main, and never rewrite commits that are already on main.
  • Never bypass git hooks with --no-verify.

Versioning

We use Semantic Versioning: MAJOR.MINOR.PATCH.

Increment When
MAJOR Breaking changes to an API or contract
MINOR New backwards-compatible functionality
PATCH Backwards-compatible fixes and dependency updates

New projects start at v0.1.0 and move to v1.0.0 when the interface is stable. How releases are cut is described in CI/CD and Deployments.