DEV Community

loading...

Discussion on: Being intentional with commits

Collapse
mindstormer619 profile image
Siddarth Iyer

One particular commit format I've found which works really well in creating commits with intent is the following:

{Commit message one-liner}

## Motivation

{Couple lines explaining *why* the change is being made.}

## Design

{Couple lines explaining *what* is being done. Not "how",
but "what".}

{Link to a design wiki/document for the change, if any.}

## Misc

{List of links to supporting material, if any. For instance,
a code-review link if you're using an external tool for this.}

An example toy commit message would read like this:

Add splash screen before MainActivity launch

## Motivation

Previously, on app launch, MainActivity would load and display an empty spinner
for up to 1.5 seconds while data was fetched from the server. This was
determined to result in poor UX for the user (see #54).

Therefore, we add a splash screen to display messages to the user while data is
fetched from the server to populate MainActivity.

## Design

We display a splash screen with rotating messages (new message every 2 seconds)
indicating the user to wait while the NetFetcher service gets data from the
server. Splash screen is deactivated on receiving completion event from
NetFetcher.

See Wiki-56 at <link>.

## Misc

+ Code Review: <link>

Tip: Don't create commits like this initially. Commit frequently on your local feature branch as your fancy strikes, and don't be afraid to write minimal descriptions on your messages. However, when the time comes to push your commits up to your main shared branch, rebase your feature commits into one, and write a commit message like this one.

Collapse
qm3ster profile image
Mihail Malo

This is a good template for pull requests, but personally I don't recommend squishing pull requests into one commit.

Collapse
mindstormer619 profile image
Siddarth Iyer

May I know why you recommend not squashing commits for smaller PRs? I can see it shouldn't be done for larger PRs, but for simpler single-feature stuff (which you'd get anyway on frequent integration) setting a single commit would work well. You'd have a relatively cleaner git history and quick reverts if needed as well.

Thread Thread
qm3ster profile image
Mihail Malo

I find it better to have more commits for git-bisect.
Then it ends up being a specific incorrect refactor, which can be made an example of, by adding regression tests, mentioning it in team guidelines, adding lints etc.
When you want to revert the whole merge, you can still use a UI button or git revert -m 1 <merge-commit>.
As for full diffs, it's just as easy to diff two arbitrary points as the state before and after a single commit.
I just don't think it brings anything useful to the table.
Maybe it's appropriate to squash-merge to the release(not master) branch in a non-CD situation. Not sure.