Branch naming convention (BRANCH CONVENTION)

This document is for template maintainers. End users are guided by (1) the collapsible guide in the issue helper comment (at the moment of use) and (2) the header comments of the dependent workflows (copied into user repositories).

Format

{prefix}YYYYMMDD_#issueNumber_normalizedTitle
e.g.: 20260712_#427_드롭다운_디자인_변경

• Generated by: .github/scripts/issue_helper.py (suggested in a comment when an issue is created) and scripts/common/gh_branch.py (the pro-github skill). The two implementations must produce the same result.
• The prefix (e.g. feat/) is optional: metadata.template.options.issue_helper.branch_prefix in version.yml.
• The core part (YYYYMMDD_#number_title) is fixed. The consumers below parse it by machine.

Consumers (what breaks if this format breaks)

Consumer	How it parses	Symptom when broken
PROJECT-FLUTTER-ANDROID-TEST-APK.yaml	sed 's/.*#\([0-9]*\).*/\1/p'	Issue information missing from the build notes
PROJECT-FLUTTER-IOS-TEST-TESTFLIGHT.yaml	Same	Same
PROJECT-FLUTTER-PROJECTOPS-APP-BUILD-TRIGGER.yaml	/#(\d+)/ plus the ### 브랜치 ("Branch") code block of the guide comment (Guide by ProjectOps, or the old Guide by SUH-LAB)	Builds triggered from issue comments cannot find the branch
scripts/common/issue_number.py (pro-commit/report/review)	Worktree \d{8}_(\d+)_ / branch number pattern	Issue number not recognized in commit messages and reports

Comment contract (the comment the issue helper generates)

The structure of the ### 브랜치 heading plus a code block is fixed. Old versions of BUILD-TRIGGER keep running in user repositories, so backward compatibility is required.

The signature (default Guide by ProjectOps) can be changed with the issue_helper.guide_signature setting. Old consumers look for the old text Guide by SUH-LAB, so the comment always keeps one line with the old marker as an invisible HTML comment. When you build a new consumer, accept both texts.

Extension rules (agents must read)

• When a new workflow starts depending on this branch convention:
  1. Add one line (file name, guide text) to GUIDE_LINES in issue_helper.py. It is based on whether the file exists, so repositories without that workflow do not show the guide (no false guidance).
  2. Add the standard "⚠️ 브랜치 규칙 의존" (depends on the branch convention) comment block to that workflow's header.
  3. Add a row to the consumer table in this document.