Dev conventions

Development Conventions

Branch Naming

Follow the format <prefix>/<issue-id>-<short-description> for all branches.

Prefixes

Prefix	Purpose
feature/	New functionality
bugfix/	Bug fixes
docs/	Documentation changes
refactor/	Code restructuring
test/	Test additions or improvements

Rules

• Always branch from origin/main. Pull latest before branching.
• Use kebab-case for the description portion.
• Always include the issue ID after the prefix.
• Keep descriptions short but meaningful (3-5 words max).

Examples

feature/42-add-user-authentication
bugfix/87-fix-date-parsing
docs/15-update-api-reference
refactor/63-extract-validation-logic
test/29-add-edge-case-coverage

Creating a Branch

git fetch origin
git checkout -b feature/42-add-user-authentication origin/main

---

Commit Messages

Use the Conventional Commits specification: <type>(<scope>): <description>.

Commit Types

Type	When to Use
feat	New feature or capability
fix	Bug fix
docs	Documentation only
refactor	Code change that neither fixes nor adds
chore	Build, tooling, or dependency changes
test	Adding or correcting tests
ci	CI/CD pipeline changes

Scope

Scope is optional. Use it to indicate the affected module, component, or issue number.

• Module scope: feat(auth): add OAuth2 support
• Issue scope: fix(#141): resolve null pointer on empty input

Description Rules

• Use imperative mood: "add feature" not "added feature" or "adds feature".
• Keep the first line under 72 characters.
• Do not end with a period.
• Lowercase the first word of the description.

Examples

feat(auth): add JWT token refresh endpoint
fix(#87): handle empty date strings in parser
docs: update installation instructions
refactor(validation): extract email validation to shared module
test(#29): add boundary tests for pagination
chore: upgrade typescript to 5.4
ci: add e2e test stage to pipeline

Multi-Line Commits

For complex changes, add a body separated by a blank line:

feat(dashboard): add real-time notification panel

Implement WebSocket-based notification system that displays
alerts in the top navigation bar. Notifications are grouped
by type and can be dismissed individually.

Closes #42

---

Label System

Apply labels to issues and pull requests for categorization and filtering.

Default Labels

Label	Purpose
epic	Large multi-issue initiative
bug	Something broken that needs fixing
feature	New functionality request
documentation	Documentation improvements
discussion	Open-ended topic for exploration
question	Clarification needed

Label Rules

• Assign one primary label per issue. This determines the issue type.
• An issue may carry additional secondary labels for cross-cutting concerns, but exactly one of the default labels must serve as primary.
• Match the label to the branch prefix when creating a branch (e.g., bug label maps to bugfix/ prefix).

---

Protected Branches

Default Protected Branch: main

The main branch enforces the following rules:

• No direct commits. All changes enter through pull requests.
• Squash and merge as the merge strategy. Keep the commit history clean.
• Required reviews before merging (configured per repository).
• Status checks must pass before merge is allowed.

What This Means in Practice

• Never commit directly to main.
• Always create a feature/bugfix branch first.
• Submit a pull request for review.
• Use squash merge to collapse branch commits into a single clean commit on main.

---

Recovery: Accidental Work on Protected Branch

When work has accidentally been done on main or another protected branch, recover without losing changes:

Steps

1. Stash current changes:

   git stash
   

2. Create and switch to the correct branch:

   git checkout -b feature/42-the-intended-branch origin/main
   

3. Apply stashed changes:

   git stash pop
   

4. Continue working on the correct branch.

If Commits Were Already Made on main

1. Note the commit hashes of the accidental commits.
2. Create a new branch from the current state:

   git checkout -b feature/42-the-intended-branch
   

3. Reset main back to match origin:

   git checkout main
   git reset --hard origin/main
   

4. Switch back to the feature branch and continue:

   git checkout feature/42-the-intended-branch
   

---

Quick Reference

Convention	Format
Branch name	<prefix>/<issue-id>-<short-description>
Commit message	<type>(<scope>): <description>
Merge strategy	Squash and merge
Protected branch	main
Primary label	One per issue

---

Dependencies

None -- this is a foundation workflow skill.

Used By

Component	Reason
issue-workflow	Steps 3 and 7 reference branch naming, commit format, and merge strategy
Command: pick-issue	Uses branch prefix mapping from this skill
Command: develop	Uses conventional commit format
Command: submit-pr	Uses PR title format derived from branch prefix