Conventional Commits

The content of this commit is left as an exercise for the reader.

We follow the Conventional Commits specification for commit messages.

When you hit enter after doing git commit, it will trigger a Git Hook managed by Husky, which triggers a Commitlint command to verify that your commit message meets the specified guidelines. Any messages that do not follow the specification will be rejected with feedback locally.

In order to ease the process of learning the specification and writing compliant commit messages, we've configured Commitizen to guide you through the process of writing a commit message interactively. You can run pnpm commit to use this tool. This will guarantee that your commit messages are formatted correctly.

With time, writing conventional commit messages will become second nature and you will no longer need to use Commitizen :)

• Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
• Each commit should be able to stand on its own, and each commit should build on the previous one. This way, if a commit introduces a bug, it should be easy to identify and revert.
• Each commit should be deployable and not break the build, tests, or functionality.
• If you're not sure if a commit should be split, it's better to split it if each commit is deployable and doesn't break the build, tests, or functionality.
• If you fixed changes in a past commit, use git commit --amend to add changes to the previous commit rather than creating a new one; thus keeping the commit history clean and concise.
  • Only exception to this is if the commit already existed on the main branch, in which case a fixup commit should be made rather than an amend. If that commit is amended and force pushed, it will diverge the git history for the entire team.
• If you ever amend, reorder, or rebase, your local branch will become divergent from the remote for the amended commit(s), so GitHub won't let you push. Simply force push to overwrite your old branch: git push --force-with-lease.

The slight learning curve of writing conventional commits is well worth the effort. It allows us unlock some pretty powerful DevOps which saves the entire team a lot of time in the long run.

Commit Message Decision Tree

Type

Scope Parameters

First level

Second level

The platforms should always be in the same order: docs, web, portal. If you have changes in the portal only, the scope should be portal. If you have changes in all three platforms, the scope should be docs,web,portal. If you have changes in docs, and web , the scope should be docs,web, and web,docs,

If it was E2E tests, change them to be their e2e counterparts, for example, docs-e2e, web-e2e, portal-e2e.

Examples

Here are some examples of commit messages following the decision tree guidelines:

# Hacker Portal bugfix that affects the UI
fix(ui/portal): dashboard login button misaligned on mobile
 
# Change in a configuration file in the Hacker Portal
fix(config/portal): add default coverage directory to jest config
 
# A new feature in the API for both the Marketing Website and Hacker Portal, no change in the UI
feat(api/web,portal): create user data retrieval endpoints
 
# A change in the build process for the Docs Site
build(docs): update webpack configuration for bundling mdx files
 
# Change in documentation content on the Docs Site
docs(contribution-guidelines): add pnpm install commands
 
# Change in UI feature on the Docs Site
feat(ui/docs): change header search bar background to purple-300
 
# A performance optimization in the API for the Hacker Portal
perf(api/portal): optimize database queries for sponsor data
 
# A code styling update for button components in the marketing website
style(web/components): change button border radius to 5px
 
# Testcase refactor for Hacker Portal
refactor(test/portal): re-structure user registration cases