Skip to content

Add commit messages documentation #156

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
runephilosof-abtion wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add commit messages documentation #156

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions technical_practices/commit_messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Commit Messages

The most important information in commit messages is *why* you made the change.

Nice to have:

* Summary of the changes (it helps when going back in history and trying to decide whether a change was accidentally added to commit).
* Thoughts about decisions you made.
* Links to Asana task, or other relevant info like a Github bug report, stackoverflow, etc.
* Keep the headline less than 50 characters, if possible.

https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/
> To come up with thoughtful commits, consider the following:
> * Why have I made these changes?
> * What effect have my changes made?
> * Why was the change needed?
> * What are the changes in reference to?
Comment on lines +1 to +17
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This is a great start for documenting commit message best practices. To make it even more effective and easier for developers to follow, I suggest restructuring the entire document. A more formal structure with sections for Headline, Body, and Footer can provide clearer, actionable guidance. This revised structure incorporates all your original points while also adding other common best practices, like using the imperative mood and linking to the Conventional Commits standard. It also aligns the formatting with other documentation files in the repository by using a 'Further reading' section.

# Commit Messages

The most important information in a commit message is *why* you made the change. A well-crafted commit message is a gift to your future self and your teammates.

## Structure of a good commit message

A commit message consists of a headline (or subject), an optional body, and an optional footer.

### Headline
The headline should be a concise summary of the change.
* Keep it under 50 characters if possible.
* Write it in the imperative mood (e.g., "Fix login bug" not "Fixed login bug").

### Body (Optional but recommended)
The body is where you explain the context and the *why*.
* Explain the problem this change is solving.
* Describe the decisions you made and their rationale.
* Summarize the changes if the headline isn't sufficient.

### Footer (Optional)
The footer is for metadata.
* Link to Asana tasks, GitHub issues, or other relevant resources (e.g., `Fixes #123`, `Refs: ASANA-456`).

## Guiding Questions
To help write a thoughtful commit message, consider these questions:
* Why is this change necessary?
* How does it address the issue?
* What effects does this change have?

## Further reading
* [How to Write Better Git Commit Messages](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/)
* [Conventional Commits](https://www.conventionalcommits.org/)