Git Workflow

Branching Model: GitLab Flow

main                    ← production-ready, protected
  └── develop           ← primary development line
        ├── feature/*   ← new features
        ├── bugfix/*    ← bug fixes
        └── hotfix/*    ← critical production fixes

• Feature/bugfix branches → develop via squash merge
• develop → main via merge commit (preserves release boundary)
• Hotfixes branch from main, merge to both main AND develop

Branch naming

<type>/<author>/<short-description>

Type	Purpose
feature	New functionality
bugfix	Fix a bug
hotfix	Critical production fix
chore	Maintenance, dependencies
docs	Documentation only
refactor	Code restructuring
test	Add/update tests

Rules: lowercase + hyphens, include author name, 3-5 word description, branch from develop.

Examples:

• feature/ducbach/role-permission-crud
• bugfix/phat/pagination-reset-on-filter
• hotfix/phat/payment-webhook-timeout

Commit Convention: Conventional Commits

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Type	Description	SemVer
feat	New feature	MINOR
fix	Bug fix	PATCH
refactor	Code restructuring (no behavior change)	—
perf	Performance improvement	PATCH
test	Add/update tests	—
docs	Documentation only	—
style	Formatting, whitespace	—
build	Build system, dependencies	—
ci	CI/CD pipeline changes	—
chore	Maintenance tasks	—

Scope

Use the package or app name: core, identity, commerce, sale, finance, payment, inventory, signal, client, bo, mq-pay, iiapi, t-van, ledger, pricing, licensing, taxation, outreach

Examples

feat(identity): add role-based access control with Casbin policies
fix(sale): prevent race condition in concurrent checkout
refactor(core): extract auth middleware into reusable component
perf(commerce): add Redis caching for product catalog queries
test(licensing): add license lifecycle integration tests
docs(identity): update API endpoint documentation
build: upgrade Bun to 1.3.x and update lockfile
feat(identity)!: change authentication to JWKS-based verification

BREAKING CHANGE: All services must update their auth configuration.

Rules

1. Imperative mood — "add feature" not "added feature"
2. No period at end of description
3. 72 chars max for the first line
4. Body explains "why" not "what"
5. Breaking changes use ! before colon OR BREAKING CHANGE: footer
6. Reference issues in footer: Closes #123 or Refs NXET-456

Merge Request Conventions

Title format

Same as Conventional Commits: <type>[scope]: <description>

Rules

1. Small MRs — target ~200 lines. If > 500 lines, consider splitting.
2. Self-review first — review your own diff before requesting review.
3. Draft MRs — use draft status for work-in-progress.
4. One MR = one concern — don't mix features with refactoring.
5. Tests included — new functionality must include tests.
6. No broken builds — CI must pass before requesting review.
7. Remove source branch — always delete the branch after merge.
8. Squash commits — squash before merge for clean history.

Merge strategy

Merge direction	Strategy
Feature branch → develop	Squash merge (clean linear history)
develop → main	Merge commit (preserves release boundary)
Hotfix → main	Merge commit with --no-ff

Golden rule: Never rebase commits that have been pushed to a shared branch.

Code Review: Conventional Comments

Use labeled comments for clarity:

Label	Meaning	Blocking?
praise:	Highlight something good	No
nitpick:	Trivial style/preference	No
suggestion:	Propose an improvement	No
issue:	Specific problem found	Yes
question:	Need clarification	No
thought:	Idea sparked by the code	No
todo:	Small necessary change	Yes
chore:	Simple required task	Yes

Examples:

praise: Clean abstraction — this makes the DI pattern much clearer.

issue: This query runs inside a loop, creating an N+1 problem.
Consider using a bulk fetch with `inArray()`.

suggestion (non-blocking): Could extract this validation into a
shared Zod schema since it's duplicated in 3 controllers.

question: Is this timeout intentional? 30s seems high for a
health check endpoint.

What to review (priority order)

1. Design — does the architecture fit IGNIS patterns?
2. Correctness — logic errors, edge cases, error handling
3. Security — auth, input validation, credential exposure
4. Performance — N+1 queries, missing caching, blocking operations
5. Tests — coverage, edge cases, meaningful assertions
6. Naming & readability — clear names, appropriate comments
7. Style & consistency — TypeScript strict, path aliases, i18n objects

Review speed

• Respond within 1 business day (ideally within a few hours)
• For large MRs, provide design feedback first before detailed review
• If a review will take time, acknowledge: "Will review by EOD"

glab CLI Reference

Setup

glab auth login --hostname git.nexpando.com    # initial setup
glab auth status                                # verify connection

Merge requests

# List
glab mr list                           # open MRs in current project
glab mr list --assignee=@me            # my MRs
glab mr list --reviewer=@me            # MRs I need to review
glab mr list --merged --per-page=50    # recently merged

# View & review
glab mr view <id>                      # view MR details
glab mr view <id> --comments           # with discussion threads
glab mr diff <id>                      # view full diff
glab mr checkout <id>                  # checkout MR branch locally

# Create
glab mr create --fill                  # auto-fill from commits
glab mr create --fill --draft          # create as draft
glab mr create -t "title" -d "desc" --assignee user --reviewer reviewer
glab mr create --fill --target-branch develop --assignee @me

# Actions
glab mr approve <id>                   # approve
glab mr merge <id> -s -d               # squash merge + delete source branch
glab mr note <id> -m "comment"         # add comment
glab mr update <id> --ready            # mark as ready (remove draft)
glab mr close <id>                     # close without merging

Issues

glab issue list                        # all open issues
glab issue list --assignee=@me         # my issues
glab issue create -t "title" -d "desc" -l bug
glab issue view <id>
glab issue close <id>

CI/CD

glab ci list                           # list pipelines
glab ci status                         # current branch pipeline
glab ci status --live                  # real-time monitoring
glab ci view --web                     # open in browser

Useful patterns

# Quick approve + squash merge
glab mr approve <id> && glab mr merge <id> -s -d

# Create MR from current branch
glab mr create --fill --target-branch develop --assignee @me

Git Hooks

The project uses .githooks/ configured via make setup-tools:

Hook	What it does
pre-commit	Runs make pre-commit → lint all packages

make setup-tools    # enable hooks (run once after clone)

Security Review Checklist

For every MR, verify:

• [ ] Auth strategies applied where needed (jwt/basic)
• [ ] No hardcoded credentials or secrets
• [ ] Proper role checks for protected endpoints
• [ ] Casbin policies updated if access rules changed
• [ ] All user input validated with Zod schemas
• [ ] No raw SQL (Drizzle ORM parameterizes queries)
• [ ] Sensitive data not logged (passwords, tokens, PII)
• [ ] API responses don't expose stack traces
• [ ] JWT tokens have appropriate expiration

Troubleshooting

Merge conflicts:

git checkout develop && git pull
git checkout <your-branch>
git rebase develop
# resolve conflicts, then: git add <files> && git rebase --continue

Undo last commit (not pushed):

git reset --soft HEAD~1

Clean build after branch switch:

bun run rebuild    # in the affected package

Related Pages

Page	Description
Getting Started	Initial setup
Build System	Make targets and build order
IGNIS Patterns	Framework patterns to follow