Development Flow

Branch Strategy

As shown in the diagram below, the develop branch is branched off from the main branch, and feature branches (feature/xxx) are branched off from the develop branch for development. The main branch is the release branch, while the develop branch is for development.

The develop branch always maintains the latest merged code, so when performing hotfixes, branches are created from the develop branch for the necessary fixes.

Work branches off develop and returns by squash-merged PR; releases go from develop to main through the release PR and a version tag.

Branch Naming

While there are no strict rules, the following naming conventions are recommended:

• feature/xxx: (xxx represents the feature being added)
• bugfix/xxx: (xxx represents the bug being fixed)
• hotfix/xxx: (xxx represents the urgent fix)

Conventional Commits

The commit messages should preferably follow the Conventional Commits guidelines.

Commit Message Format

By using .gitmessage, a template for commit messages is provided. This template can be enabled locally for this project by configuring git config --local.

git config --local commit.template .gitmessage

Once configured, running git commit will display the contents of .gitmessage in your editor (Vim by default).

git commit
# Overview (Uncomment one of the following templates)
#feat:
# └  A new feature
#fix:
# └  A bug fix
#docs:
# └  Documentation only changes
#style:
# └  Changes that do not affect the meaning of the code
#    (white-space, formatting, missing semi-colons, etc)
#refactor:
# └  A code change that neither fixes a bug nor adds a featur
#test:
# └  Adding missing or correcting existing tests
#ci:
# └  Changes to our CI configuration files and scripts
#chore:
# └  Updating grunt tasks etc; no production code change

Select the appropriate template and uncomment it, then write your commit message.

docs: Update README.md
# └  Documentation only changes

Correspondence between Commit Messages and Labels

When creating a PR to the main branch, labels are automatically assigned based on the commit messages. Below is the correspondence between prefixes and labels:

Prefix	Label	Description
feat:	feature	Adding a new feature
fix:	bugfix	Bug fixes
docs:	documentation	Documentation only changes
style:	style	Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor:	refactor	Code changes that neither fix a bug nor add a feature
test:	test	Adding or correcting existing tests
ci:	ci	Adding or updating CI configuration and scripts
chore:	chore	Minor changes or maintenance tasks

Secret Scanning

Betterleaks runs on every commit via a Lefthook-managed pre-commit hook and blocks the commit on any finding. Trufflehog scans git history in CI for verified leaks. See Credential Scanning for tool roles, output reading, and false-positive handling.

Command	Description
task scan-leaks	Scan the entire repository with Betterleaks
task scan-leaks-local	Scan tracked working files and commits absent from the target branch
task scan-leaks-staged	Scan staged files only
task scan-secrets	Scan git history with Trufflehog (verified secrets only)
task scan-secrets-all	Scan git history with Trufflehog (all findings)

task check includes scan-leaks-local. The default target is origin/develop; use task check LEAKS_BASE=origin/main for another target. See the local scan boundaries for prerequisites and excluded files.

Pull Requests

Open pull requests against develop unless the release process requires another base branch. Use the repository pull request template and keep the description focused on the behavior change, important implementation notes, and verification performed.

Before Pushing

Every push requires a successful task check on the content being pushed, including documentation-only changes and updates to existing PRs. Focused tests during development, pre-commit hooks, and CI supplement this gate.

On the host, run task check and commits inside the Nix shell, which provides the pinned Betterleaks release. In the DevContainer, run the same commands directly. task check first runs task check-betterleaks-version and stops if the betterleaks on PATH is a different release; see scanner version.

Stage intended new files so the leak scan includes them. Fetch the PR target branch to refresh its local reference, then run the check from the repository root:

git fetch origin develop
nix develop -c task check

For a different PR target, fetch that branch and set LEAKS_BASE, for example:

git fetch origin main
nix develop -c task check LEAKS_BASE=origin/main

Commit with nix develop -c git commit so the pre-commit hook uses the same scanner.

task check runs auto-fixing linters. Review the resulting diff and include intended fixes in the commit. If you edit files after the check, rerun it before pushing. Require exit status 0; if the check fails or cannot run, resolve the failure before pushing. Report the failed command and reason if blocked, and do not push.

Record the check command and result in the PR description and the agent's final handoff.