# Conventional Commits

Conventional Commits is a way to write Git commit messages that can help us automate the generation of changelogs. Good changelogs help us keep track and communicate changes in a standardized way accross all our projects.

To be more specific, this method of writing Git commit messages currently automates the following:

- Generation of changelogs via [Release Please](https://github.com/googleapis/release-please)
- Create tags and releases on GitHub. ([Example](https://github.com/googleapis/release-please/releases))
- Update the Semantic Version numbers in relevant files according to the commited changes

Without Conventional Commits, the above changelogs and releases will be vague (i.e. we can't know what changed in each release). In short, we are using it as a way to effortlessly create documentation as we go.

## Learn it in 10 minutes

Use `feat: ` for new things and abilities. Examples:

```
feat: add product overview
feat: add payment detail screen
feat: add invoice detail endpoint
feat!: new overall app layout
```

Use `fix: ` for fixing an existing thing. Examples:

```
fix: correct auto-complete type in input fields
fix: remove excessive calls to endpoint X
fix: correct a typo
fix!: handle edge case in endpoint Y with new required params
```

Use `chore: ` for changes that are important but not really a feature nor a fix. Example:

```
chore: upgrade framework A version
chore: upgrade library B
chore!: drop support for environment C
chore: update product logo image
chore: update copy text for common buttons
```

The above three prefixes are arguably the most important things we want to track, which is also laid out as "Features", "Bug Fixes", and "Miscellaneous" in our [changelog generation script](https://github.com/TinkaTech/github-provisioning/blob/master/workflows/github-workflows/release-please/workflow.yml).

There are other prefixes (a.k.a. types) you could use if you are really into typing things. Strategical use of these types can help exclude trivias from the changelog.

```
refactor: make file X more readable
refactor: remove overly-nested ifs in file X
docs: document feature XYZ
docs: add some comment on a weird feature
test: add unit test for file X
revert: revert a previous commit X
revert: revert a previous feature Y
```

Specify a scope to make the generated changelogs to highlight and group things for you. This is especially [useful in monorepos](https://github.com/TinkaTech/tinka-ui/blob/main/CHANGELOG.md).

```
feat(react): add slider component
feat(flutter): add slider component
fix(react): fix a typo in the slider component
fix(flutter): fix incorrect assignment of props in slider component
chore(web)!: update web dependency X that is super critical
```

Mention the JIRA ticket identifier in the body of the commit message. Example:

```
fix(profile-page): use namePrefix when showing fullName

ABC-1234
```

## Use Conventional Commits with Pull Requests

The most important pratice is to write Pull Request titles in the format of Conventional Commits. When merging the PR, choose **Squash and merge** to maintain clear history in the branch that the PR is merging into.

## Further Information

- [Why use Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#why-use-conventional-commits)
- [Summary of the specification](https://www.conventionalcommits.org/en/v1.0.0/#summary)