Code Commits

Changes in a commit

Think of your commit as a single step in a series of progressive works. Other developer should be able to see your progress from a series of commits in a clear and descriptive way.

Convention

• stands alone as a single, complete, logical change
• has no extraneous modifications from different task or fix
• has a descriptive commit message (see below)

Commit message

A clear commit message is very important for the following reasons:

• A simple navigation through git history (e.g: ignoring style changes)
• Automatic generation of the changelog
• Commit based CI/CD pipeline step (e.g: don't trigger build and deploy if the change is only about documentation or styling)

Convention

Use the following format,

type(scope): [issue] subject

body

type is mandatory and must be one of the following:

• feat: A new feature
• fix: A bug fix
• build: Build related changes (eg: npm related/ adding external dependencies)
• chore: A code change that external user won't see (eg: change to .gitignore file or .prettierrc file)
• docs: Documentation related changes
• refactor: A code that neither fix bug nor adds a feature. (eg: You can use this when there is semantic changes like renaming a variable/ function name)
• perf: A code that improves performance
• style: A change that is related to code style or lint (e.g: fix indentation, missing semicolons or whitespaces)
• test: Adding new test or making changes to existing test

scope is optional and must follow these rules:

• A phrase describing parts of the code affected by the change. For example "(seeder)" or "(middleware)"
• Small caps with dash (-) as separator. For example "(web-server)" or "(storage-service)"
• It can be empty when the change is a global or difficult to assign to a single component, in which case the parentheses are omitted

issue is mandatory whenever the change relates to a work item in JIRA or other project management tool, and must follow these rules:

• The issue ID in square brackets and in capital letters. For example "[PHOL-19]" or "[INA28-272]"
• Put it after the colon and before the subject, with a single space on both sides
• Use more than one when the change covers several work items. For example "[PHOL-31] [PHOL-32]"
• Leave it out only when there is no work item at all, such as a release chore or repository setup
• When you are not sure which work item a change belongs to, ask instead of leaving it out

subject is mandatory and must follow these rules:

• In English
• Use a single space after colon
• A single sentence only
• Imperative, present tense (eg: use "add" instead of "added", "adding" or "adds")
• Don't use dot (.) at the end
• Don't capitalize first letter

body is optional and must follow these rules:

• In English
• Use a blank line to separate with the subject
• Used only when further explanation is required or change contains several parts
• Maximum 72 characters per line
• Use bullet points if needed
• Multi line is ok
• Capitalize is ok

Keep it short. The issue ID is already in the subject, so anyone who wants the full story opens the work item. Don't put the following in the body:

• Why one approach was chosen over another, or what was tried first
• How the fix works step by step, function names or file walkthroughs
• Benchmark tables, before and after timings, row counts or percentages
• Proof of testing: what was run, what was compared, which cases were covered
• A list of extra clean ups that came along with the main change

If the body only repeats what the diff or the work item already says, remove it.

Examples

fix(middleware): [PHOL-19] ensure Range headers adhere more closely to RFC 2616

feat(store): [PHOL-24] add multi shift support to store operational hours

- Modify Update Store Operational Hours API endpoint
- Update query list store to support multi shift

feat(storage): [PHOL-31] [PHOL-32] add AWS S3 support

refactor: [PHOL-40] move all auth functionalities to a separate module

The three below have no work item, so they carry no issue ID.

chore: release 2.0.1

build: bump axios to 0.21.1

style: replace CRLF to LF