Git workflow

Branch modelCopy Anchor Link

The repository owner is Anis for hoco and Imad for hoco-mobile. Dependabot opens its own dependabot/… branches into dev.

NamingCopy Anchor Link

Format: <type>/<TASK-ID>-<short-description>.

• type is one of feature, fix, chore, docs, release, hotfix.
• The task id is written exactly as in the plan (uppercase: SRV-14, MDA-05). A bug without a task uses its issue number (fix/57-…).
• The description is 2 to 5 lowercase ASCII words in kebab-case; the whole name stays under 50 characters.
• release/ and hotfix/ carry the version only.

Merge policyCopy Anchor Link

• Into dev: squash merge. The PR title becomes the commit subject on dev, so the PR title must itself be a valid Conventional Commit with the task id. The body keeps Closes #n.
• release/x.y.z into master: merge commit (never squash), then the repository owner tags the merge commit with an annotated tag (git tag -a v1.0.0 -m "HOCO 1.0.0") and opens the back-merge PR master → dev, merged with a merge commit.
• Fixes during acceptance branch from release/x.y.z and merge back into it. The repository owner merges release/x.y.z into dev after each -rc.N tag, so dev never lacks a fix.
• hotfix/x.y.z: merge commit into master, tag, then back into dev (and into an open release/*, if any).
• Syncing your own branch: rebase on origin/dev, then git push --force-with-lease. Never rebase dev, master, release/*, or a branch someone else has pushed to. Never merge dev into a feature branch, except when two people share it.
• No cherry-picks between dev and a release branch, except a hotfix that must also reach an open release branch (git cherry-pick -x, to keep the reference).

A feature, end to end:

git switch dev && git pull --ff-only
git switch -c feature/SRV-14-crm-module
# … work, commit in small steps …
git fetch origin && git rebase origin/dev        # at least daily
git push -u origin feature/SRV-14-crm-module     # first push
git push --force-with-lease                      # after a rebase
gh pr create --base dev --title "feat(server): reseller lifecycle transitions [SRV-14]"

Conventional CommitsCopy Anchor Link

Format: <type>(<scope>): <subject> [TASK-ID]

• The subject is imperative, starts lowercase, has no final period. The whole header is at most 100 characters (commitlint header-max-length).
• The task id goes at the end in brackets: [SRV-16], or [SRV-16, SRV-17] for two tasks. It is omitted only for chores and bugs without a task.
• The body says why when it is not obvious. Footers: Closes #42, Refs #57, BREAKING CHANGE: ….
• Breaking changes add ! after the scope. For the API contract, a breaking change also follows the deprecation process — it is never shipped in place.

Scopes in hoco:

Scopes in hoco-mobile:

commitlint enforces the format and the type. The scope list is enforced in review: since dev only receives squash commits, the PR title is what lands, and the reviewer renames an unknown scope before merging.

feat(contracts): add delegate visit check-in operations [SRV-03]
feat(server): implement cart.checkout with stock and credit checks [SRV-15]
fix(server): release reserved stock when an order is cancelled [SRV-16]
feat(server): after-sales claims and returns with automatic restock [SRV-20]
feat(db): add Tour, Visit and VisitReport models [SRV-21]
feat(dashboard): orders-to-confirm queue [DSH-06]
feat(dashboard): returns and after-sales pages [DSH-13]
docs(plan): mark SRV-03 done, re-estimate SRV-21
chore(deps): bump next to 16.4.3
refactor(env)!: rename S3_BUCKET to S3_BUCKET_PUBLIC

BREAKING CHANGE: update your local .env from .env.example.

feat(delegate): offline visit check-in with GPS tolerance [MDA-05]
feat(reseller): live order status and return requests [MRA-10]
fix(core): retry once after refreshing an expired session [MOB-02]
chore(api): regenerate client from contract 1.4.0 [MOB-03]

Commit hygieneCopy Anchor Link

• One concern per commit. Schema and contract commits come before the code that uses them.
• Stage explicitly (git add <paths>) and read git diff --staged before committing.
• Generated files are committed only where listed: the OpenAPI document (apps/docs/public/openapi/hoco-v1.json), Prisma migrations, the team-task pages (pnpm docs:generate), hoco_api and the build_runner outputs in hoco-mobile, lockfiles. Never committed: .env, the Prisma client (prisma/generated), .next, dist, APK/AAB files, keystores, service-account files.
• Lockfiles change only with a dependency change; CI installs with --frozen-lockfile.
• No commented-out code, no stray console.log or print, no TODO without an issue number (TODO(#57): …).
• Line endings are LF everywhere (.gitattributes: * text=auto eol=lf). On Windows, also set git config --global core.autocrlf input.

HooksCopy Anchor Link

• Never commit with --no-verify. A wrong hook is fixed in a PR.
• Hooks missing? Run pnpm exec lefthook install. Check with a commit message like wip: it must be rejected.
• Install gitleaks locally (Scoop: scoop install gitleaks). The hook skips it when absent, but CI scans every PR anyway.

Keep branches shortCopy Anchor Link

• Three working days at most from first commit to merge. A PR without activity for two working days is mentioned in the stand-up.
• A task longer than two days ships as several PRs under the same task id, each leaving dev deployable. Typical order: contract → schema and migration → endpoints → back-office or app screens.
• Unfinished work lands hidden: operations not yet called, back-office routes not in the navigation, app screens behind a release flag (feature flags). Anything visible but unfinished is behind a flag before the next release cut.
• Rebase on dev at least once a day, and right away when a contract or migration PR lands.

Database migrations in branchesCopy Anchor Link

The schema is multi-file Prisma in packages/db/prisma/schema/; migrations live in packages/db/prisma/migrations/.

pnpm --filter @hoco/db exec prisma migrate dev --name srv14_crm_core
# review or edit the SQL before applying (renames, backfills):
pnpm --filter @hoco/db exec prisma migrate dev --create-only --name srv14_crm_core

Rules:

• A migration that has reached dev is never edited. Fix forward with a new one.
• Expand, then contract. The new api container applies migrations when it starts, while the previous version may still be serving (architecture). A migration must therefore work with the code currently in production: add nullable columns and new tables first; rename, drop or set NOT NULL in a later release, after a backfill.
• Destructive statements (DROP, ALTER COLUMN … TYPE, SET NOT NULL, a unique index on a populated table) are read line by line by the reviewer, and the PR explains the plan.
• Reference data (wilayas, roles and permissions, settings defaults, reference lists) changes through idempotent seeds, never through manual SQL on an environment.
• pnpm db:push is for a throwaway local database only, never for anything that will be committed.

The same rules in hoco-mobileCopy Anchor Link