> For the complete documentation index, see [llms.txt](https://docs.shiftiq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shiftiq.com/contributors/conventions/git-commits.md).
# Git commits
Conventions for commit messages
[Conventional Commits](https://www.conventionalcommits.org/) are recommended for Shift iQ code repositories.
**Important —** Whenever a Jira issue is associated with a code change, prefix the commit message with the Jira issue number. This is especially important in the internal `insite/code` repository.
* **Example** — `TEC-1234 fix: add missing filter for project search`
***
#### Format
```
():
```
#### Rules
* **Type** — lowercase, from the list below.
* **Scope** — optional, lowercase, parenthesized (e.g. `feat(auth):`).
* **Description** — lowercase, imperative mood ("add" not "added" or "adds"), no trailing period, \~50 characters max.
* **Body** — optional. Wrap at \~72 characters. Separate from the subject with a blank line. Explain *why*, not *what*.
* **Footer** — optional. Used for breaking changes and issue references.
#### Types
| Type | Use for |
| ---------- | ------------------------------------------------------------------- |
| `feat` | A new feature |
| `fix` | A bug fix |
| `docs` | Documentation only |
| `style` | Formatting, whitespace — no code change |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `build` | Build system or dependencies (NuGet, `.csproj`, Astro config, etc.) |
| `ci` | CI configuration |
| `chore` | Maintenance with no production impact |
| `revert` | Reverts a previous commit |
#### `ci:` vs `build:` vs `chore:`
A boundary worth knowing, because it trips people up:
* `ci:` — changes to CI/CD pipeline files (e.g. `.github/workflows/*.yml`, `azure-pipelines.yml`).
* `build:` — changes to the build system itself or its dependencies (e.g. `package.json`, `astro.config.mjs`, NuGet/`.csproj`, build scripts).
* `chore:` — maintenance with no impact on production output (e.g. `.gitignore`, editor config, repo metadata).
So `bump astro to 5.2` is `build:` (it's a build dependency), but `bump actions/checkout to v4` is `ci:` (it's only used inside a workflow).
#### Breaking Changes
Append `!` after the type/scope and include a `BREAKING CHANGE:` footer.
For example:
```
feat(api)!: drop support for legacy auth tokens
BREAKING CHANGE: legacy bearer tokens issued before v2 are no longer
accepted. Clients must re-authenticate via OAuth.
```
#### First Commits
The first commit of a new repository follows the same conventions as every other commit, including imperative mood. Prefer a descriptive verb over the traditional but noun-phrased `initial commit`.
Good:
```
chore: bootstrap portfolio
chore: initialize repository
```
Bad:
```
chore: initial commit # noun phrase, not imperative
chore: first commit # same problem
Initial commit # GitHub's default — no type prefix
```
#### When to Include a Body
Skip the body when the subject line is fully self-explanatory.
For example:
```
docs: update engagement interests
```
Include a body when the *why* isn't obvious from the *what*.
For example:
```
refactor: extract retry logic into RetryPolicy
The inline retry blocks in SyncService and ImportService had drifted
apart, making it unclear which was authoritative. Consolidating into
RetryPolicy gives them a single source of truth and makes the back-off
curve testable.
```
#### Atomic Commits
One logical change per commit. If you can't pick a single type, the commit is doing too much - split it.
#### Examples
Good:
```
chore: bootstrap repo
feat: add filter for engagement type
fix: correct broken link to LinkedIn profile
docs: update engagement interests
build: bump astro to 5.2
refactor(auth): simplify token expiry check
```
Bad:
```
Updated readme # missing type, past tense, capitalized
feat: Added new feature. # capitalized, past tense, trailing period, vague
fix: stuff # uninformative description
WIP # not a commit message
```
#### References
* [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
* Tim Pope, [*A Note About Git Commit Messages*](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.shiftiq.com/contributors/conventions/git-commits.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.