Code Computerlove logo Front End Tools & Docs

There have been a couple of attempts at creating a standard for commit messages and PRs in the past and it's a difficult thing to get right. However, it is an important aspect of the company's workflow for a number of reasons:

  • Commit messages and PRs are instantly readable by everyone
  • You should have enough information in a short space for somebody else to understand exactly what the commit is doing
  • It's very easy to create release notes (or similar) from the commit messages alone
  • If you get hit by a bus somebody else can pick up where you left off because the history of your work is written out in an easily understandable way
  • And many more

Fortunately, there is already a standard for this that is being used in some of the most popular development projects, including React (whose standards this is based on).

Conventional Commits

Have a read through the above link to understand what it's about. Here's a very brief overview:

fix: XXX-123 - this is the title of my commit with changes

Here is the main description body you need


to add more lines.

You'll notice a slight variation in the format of the above commit title where I've added a ticket number after the type. This is an important part to add because it allows people to know what ticket the commit references so they can look at that ticket to get more details on the work.

PRs

PR titles should follow the same convention as commit messages, except where multiple tickets have been worked on. In this case they should be listed in the PR description.

PR descriptions should be as descriptive as possible. Think about the description as a way for somebody else to be able to read what you have changed and immediately be able to work on it where you left off. You can add images and videos to PR descriptions if you think they would be useful. Where changes to processes are included document how to implement these changes (e.g. adding a new package to the build or a new command to run).