Commit and PR Conventions

Introduction

Clear commit messages and focused Pull Requests make history searchable and review fast. This chapter introduces Conventional Commits, PR sizing, linking Issues, and habits that keep main stable—patterns used across hello_code language tracks and real product teams.

Prerequisites

Commit Message Structure

Good default:

text

Short imperative summary (50 chars or less)
 
Optional body: why the change, not only what.
Wrap near 72 characters per line.

Example:

text

Add email validation to signup form
 
Reject empty and malformed addresses before API call.
Fixes client-side UX for error #88.

Rules:

Imperative mood: "Add feature" not "Added feature"
First line stands alone in git log --oneline
Body optional for trivial one-line fixes

Conventional Commits

Structured prefix for automation (changelog, semver bumps):

text

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

Common types:

Type	Use
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting, no logic change
`refactor`	Code change, not feat/fix
`test`	Tests
`chore`	Build, deps, tooling

Examples:

bash

git commit -m "feat(auth): add OAuth login button"
git commit -m "fix(api): handle null user id in profile"
git commit -m "docs(readme): update install steps"

Code explanation:

Tools parse prefix for release notes
Breaking change: feat!: or footer BREAKING CHANGE:

Not every repo enforces this—match your project's CONTRIBUTING file.

One PR, One Purpose

Good PR	Too large PR
Fix login validation	Login + refactor entire utils + dependency bump
Update Git chapter 14	Entire tutorial track rewrite
Add Maven surefire config	Maven + Gradle + CI + unrelated CSS

Benefits:

Reviewers understand scope in minutes
Easier revert if something breaks
CI failures map to clear cause

Split work:

text

PR 1: refactor extract validator
PR 2: feat use validator in signup

PR Description Template

markdown

## Summary
Brief what and why.
 
## Changes
- List main files or behaviors
 
## Test plan
- [ ] Unit tests pass
- [ ] Manual: sign up with invalid email shows error
 
## Related
Fixes #123

Reviewers use Test plan to verify—not guess.

Link Issues and Commits

In commit or PR:

text

Fixes #42
Closes #42
Refs #42

Code explanation:

Fixes auto-closes issue on merge (GitHub)
Refs links without closing

Keep issue title actionable: "Signup accepts empty email" not "bug".

Code Review Etiquette

Authors:

Self-review diff before requesting review
Respond to comments with commits or replies
Keep PR updated with main (merge or rebase per team)

Reviewers:

Comment on code, not people
Approve when CI green and scope clear
Block merge only for real risks—not style nitpicks unless documented

What Not to Do on main

Warning

Protected Branch Habits

No direct commits to shared main without PR
No force push to main unless incident response with team agreement
No secrets in commits—see .gitignore

FAQ

Conventional Commits mandatory?

Only if project says so—many teams use imperative summary only.

fix vs chore for dependency bump?

chore(deps): bump lodash to 4.17.21—some teams use build or deps.

Squash merge and message?

Platform uses PR title or combines commits—write good PR title.

Commit Chinese message?

This site uses English docs; team repos may allow local language—be consistent per repo.

How small is small PR?

Rule of thumb: reviewable in 15–30 minutes, under ~400 lines changed when possible.

Co-authored commits?

Co-authored-by: Name <email> in body—GitHub attributes both authors.