Version Control

23.1. GitHub Flow Branch Strategy

23.1.1. Core Principles

• The main branch must always remain in a deployable state.
• All work must be performed on feature branches created from main.
• Upon completion, a Pull Request must be created and merged into main after review.

23.1.2. Branch Naming

Prefix	Purpose	Example
feature/	New feature development	feature/user-registration
fix/	Bug fix	fix/login-redirect-error
hotfix/	Production emergency fix	hotfix/payment-null-check
chore/	Build, configuration, dependency, and other non-functional tasks	chore/update-spring-boot
docs/	Documentation work	docs/api-specification
refactor/	Refactoring	refactor/user-service-cleanup

23.1.3. Branch Naming Rules

• Only lowercase letters and hyphens (-) must be used.
• Slashes (/) must only be used for prefix separation.
• Branch names must concisely describe the task.
• If an issue number exists, it should be included: feature/123-user-registration

23.1.4. Workflow

---

23.2. Commit Message Conventions

23.2.1. Conventional Commits

All commit messages must follow the Conventional Commits format.

<type>: <description>

[optional body]

23.2.2. Type List

Type	Description	Example
feat	New feature	feat: add user profile retrieval API
fix	Bug fix	fix: resolve login redirect error
docs	Documentation changes	docs: update API specification
style	Code formatting (no behavior change)	style: sort imports
refactor	Refactoring (no behavior change)	refactor: extract UserService methods
test	Add/modify tests	test: add UserService unit tests
chore	Build, configuration changes	chore: update Spring Boot to 3.4.3
perf	Performance improvements	perf: optimize user list query
ci	CI configuration changes	ci: add CircleCI cache configuration

23.2.3. Commit Message Rules

• The subject line must be kept within 50 characters.
• The subject must be written in imperative mood. ("Added" X -> "Add" O)
• The subject must not end with a period.
• If a body is needed, it must be separated from the subject by a blank line.
• Korean or English must be used consistently on a per-project basis.

---

23.3. Pull Request Rules

23.3.1. PR Requirements

Item	Criteria
Reviewers	Approval from at least 1 reviewer
CI	All checks passed (lint, build, test)
Conflicts	All merge conflicts resolved
Branch	Up to date with main

23.3.2. PR Template

The project must include .github/pull_request_template.md.

## Changes
<!-- Briefly describe the changes in this PR -->

## Reason for Change
<!-- Explain why this change is necessary -->

## Testing
- [ ] Unit tests added/modified
- [ ] Verified locally

## Related Issues
<!-- Related issue number (e.g., #123) -->

23.3.3. Merge Strategy

• Squash and Merge must be used as the default strategy.
• After merging, the feature branch must be automatically deleted.

---

23.4. .gitignore Standards

23.4.1. Unified .gitignore Example

# Java / Maven
target/
*.class
*.jar
*.war

# Spring Boot
*.log

# IDE
.idea/
*.iml
.vscode/*
!.vscode/settings.json
!.vscode/extensions.json

# Node.js
node_modules/
dist/

# Environment Variables
.env.local
.env.*.local

# OS
.DS_Store
Thumbs.db

23.4.2. Principles

• Build artifacts (target/, dist/) must not be tracked.
• Among IDE settings, only team-shared settings (.vscode/settings.json) must be tracked.
• Local environment variables (.env.local) must not be tracked.

---

23.5. Version Tagging

23.5.1. Semantic Versioning

All releases must follow Semantic Versioning (SemVer) rules.

MAJOR.MINOR.PATCH

Component	When to Increment	Example
MAJOR	Breaking changes that break backward compatibility	1.0.0 -> 2.0.0
MINOR	Backward-compatible feature additions	1.0.0 -> 1.1.0
PATCH	Backward-compatible bug fixes	1.0.0 -> 1.0.1

23.5.2. Tag Format

• Git tag format: v{MAJOR}.{MINOR}.{PATCH}
• Example: v1.0.0, v1.2.3

git tag -a v1.0.0 -m "v1.0.0 release"
git push origin v1.0.0

23.5.3. Release Notes

Release notes describing all changes must be written for every release. Changes must be grouped by commit message type.