Commit Convention
All commits at Ilmiya follow conventional commit format with a ticket trailer on the second paragraph.
Format
type(scope): description
Linear: TEAM-NNN ← Tier 1 (Taha, Adnan — Linear access)
Refs: #NNN ← Tier 2 (all other devs — GitHub issue)
Types
| Type | When to use |
|---|---|
feat | New feature or capability |
fix | Bug fix |
chore | Maintenance, dependency updates, config changes |
docs | Documentation only |
refactor | Code change that neither fixes a bug nor adds a feature |
test | Adding or updating tests |
perf | Performance improvement |
ci | CI/CD pipeline changes |
Scopes
Match the repo or module the change is in:
| Scope | Applies to |
|---|---|
api | Backend API monorepo |
platform | Staff-facing frontend (Studio, Admin, Analytics, Console, People) |
myilmiya | Student-facing app |
devops | Kubernetes, CI/CD, deployment config |
infra | Third-party infrastructure, terraform |
safina | This repo |
Rules
- Description: lowercase, imperative mood, under 72 characters
- No period at the end
- Blank line between the subject and the ticket trailer
- One ticket per commit where possible; if a commit spans multiple tickets, list each on its own line
Examples
feat(platform): add course enrollment flow
Linear: ENG-142
fix(api): resolve auth token expiry edge case
Linear: ENG-89
chore(devops): update k8s resource limits for api services
Refs: #47
refactor(myilmiya): extract lesson progress tracking into shared hook
Refs: #103
Why this format
The Linear: and Refs: trailers are machine-readable — they’re how the bidirectional sync between Linear and GitHub knows which commit belongs to which ticket. They also make git log scannable: you can tell at a glance what was being worked on for every commit.