nofx/.github/PR_TITLE_GUIDE.md

PR Title Guide

📋 Overview

We use the Conventional Commits format to maintain consistency in PR titles, but this is recommended, not mandatory. It will not prevent your PR from being merged.

✅ Recommended Format

type(scope): description

Examples

feat(trader): add new trading strategy
fix(api): resolve authentication issue
docs: update README
chore(deps): update dependencies
ci(workflow): improve GitHub Actions

---

📖 Detailed Guide

Type - Required

Describes the type of change:

Type	Description	Example
feat	New feature	feat(trader): add stop-loss feature
fix	Bug fix	fix(api): handle null response
docs	Documentation change	docs: update installation guide
style	Code formatting (no functional change)	style: format code with prettier
refactor	Code refactoring (neither feature nor fix)	refactor(exchange): simplify connection logic
perf	Performance optimization	perf(ai): optimize prompt processing
test	Add or modify tests	test(trader): add unit tests
chore	Build process or auxiliary tool changes	chore: update dependencies
ci	CI/CD related changes	ci: add test coverage report
security	Security fixes	security: update vulnerable dependencies
build	Build system or external dependency changes	build: upgrade webpack to v5

Scope - Optional

Describes the area affected by the change:

Scope	Description
exchange	Exchange-related
trader	Trader/trading strategy
ai	AI model related
api	API interface
ui	User interface
frontend	Frontend code
backend	Backend code
security	Security related
deps	Dependencies
workflow	GitHub Actions workflows
github	GitHub configuration
actions	GitHub Actions
config	Configuration files
docker	Docker related
build	Build related
release	Release related

Note: If the change affects multiple scopes, you can omit the scope or choose the most relevant one.

Description - Required

• Use present tense ("add" not "added")
• Start with lowercase
• No period at the end
• Concisely describe what changed

---

🎯 Complete Examples

✅ Good PR Titles

feat(trader): add risk management system
fix(exchange): resolve connection timeout issue
docs: add API documentation for trading endpoints
style: apply consistent code formatting
refactor(ai): simplify prompt processing logic
perf(backend): optimize database queries
test(api): add integration tests for auth
chore(deps): update TypeScript to 5.0
ci(workflow): add automated security scanning
security(api): fix SQL injection vulnerability
build(docker): optimize Docker image size

⚠️ Titles That Need Improvement

Poor Title	Issue	Improved
update code	Too vague	refactor(trader): simplify order execution logic
Fixed bug	Capitalized, not specific	fix(api): handle edge case in login
Add new feature.	Has period, not specific	feat(ui): add dark mode toggle
changes	Doesn't follow format	chore: update dependencies
feat: Added new trading algo	Wrong tense	feat(trader): add new trading algorithm

---

🤖 Automated Check Behavior

When PR Title Doesn't Follow Format

1. Won't block merging ✅

   • Check is marked as "advisory"
   • PR can still be reviewed and merged

2. Provides friendly reminder 💬

   • Bot will comment on the PR
   • Provides format guidance and examples
   • Suggests how to improve the title

3. Can be updated anytime 🔄

   • Re-checks after updating PR title
   • No need to close and reopen PR

Example Comment

If your PR title is update workflow, you'll receive a comment like this:

## ⚠️ PR Title Format Suggestion

Your PR title doesn't follow the Conventional Commits format,
but this won't block your PR from being merged.

**Current title:** `update workflow`

**Recommended format:** `type(scope): description`

### Valid types:
feat, fix, docs, style, refactor, perf, test, chore, ci, security, build

### Common scopes (optional):
exchange, trader, ai, api, ui, frontend, backend, security, deps,
workflow, github, actions, config, docker, build, release

### Examples:
- feat(trader): add new trading strategy
- fix(api): resolve authentication issue
- docs: update README
- chore(deps): update dependencies
- ci(workflow): improve GitHub Actions

**Note:** This is a suggestion to improve consistency.
Your PR can still be reviewed and merged.

---

🔧 Configuration Details

Supported Types

Configured in .github/workflows/pr-checks.yml:

types: |
  feat
  fix
  docs
  style
  refactor
  perf
  test
  chore
  ci
  security
  build

Supported Scopes

scopes: |
  exchange
  trader
  ai
  api
  ui
  frontend
  backend
  security
  deps
  workflow
  github
  actions
  config
  docker
  build
  release

Adding New Scopes

If you need to add a new scope:

1. Add it to the scopes section in .github/workflows/pr-checks.yml
2. Update the regex in .github/workflows/pr-checks-run.yml (optional)
3. Update this documentation

---

📚 Why Use Conventional Commits?

Benefits

1. Automated Changelog 📝

   • Automatically generate version changelogs
   • Clearly categorize different types of changes

2. Semantic Versioning 🔢

   • feat → MINOR version (1.1.0)
   • fix → PATCH version (1.0.1)
   • BREAKING CHANGE → MAJOR version (2.0.0)

3. Better Readability 👀

   • Understand PR purpose at a glance
   • Easier to browse Git history

4. Team Collaboration 🤝

   • Unified commit style
   • Reduces communication overhead

Example: Auto-generated Changelog

## v1.2.0 (2025-11-02)

### Features
- **trader**: add risk management system (#123)
- **ui**: add dark mode toggle (#125)

### Bug Fixes
- **api**: resolve authentication issue (#124)
- **exchange**: fix connection timeout (#126)

### Documentation
- update API documentation (#127)

---

🎓 Learning Resources

• Conventional Commits: https://www.conventionalcommits.org/
• Angular Commit Guidelines: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit
• Semantic Versioning: https://semver.org/

---

❓ FAQ

Q: Must I follow this format?

A: No. This is recommended but not mandatory. It won't block your PR from being merged. However, following the format improves project maintainability.

Q: What if I forget?

A: The bot will remind you in the PR comments. You can update the title anytime.

Q: Can I make multiple types of changes in one PR?

A: Yes, but it's recommended to:

• Choose the most significant type
• Or consider splitting into multiple PRs (easier to review)

Q: Can I omit the scope?

A: Yes. requireScope: false means scope is optional.

Example: docs: update README (no scope is fine)

Q: How do I add a new type or scope?

A: Submit a PR to modify .github/workflows/pr-checks.yml and document the purpose of the new item in this guide.

Q: How do I indicate Breaking Changes?

A: Add BREAKING CHANGE: in the description or add ! after the type:

feat!: remove deprecated API
feat(api)!: change authentication method

BREAKING CHANGE: The old /auth endpoint is removed

---

📊 Statistics

Want to see the commit type distribution in your project? Run:

git log --oneline --no-merges | \
  grep -oE '^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|chore|ci|security|build)' | \
  cut -d' ' -f2 | sort | uniq -c | sort -rn

---

✅ Quick Checklist

Before submitting a PR, check if your title:

• Contains a valid type (feat, fix, docs, etc.)
• Starts with lowercase
• Uses present tense ("add" not "added")
• Is concise (preferably under 50 characters)
• Accurately describes the change

Remember: These are recommendations, not requirements!