Best Practices for Commit Messages on GitHub

Best Practices for Commit Messages on GitHub

When working on projects hosted on GitHub, clear and concise commit messages are crucial for maintaining a well-organized codebase. They not only help collaborators understand the history of changes but also enhance your portfolio by showcasing your professionalism and attention to detail. Here are three practical examples of best practices for commit messages on GitHub.

Example 1: Meaningful Descriptions

To ensure that your commit messages convey the necessary information, use meaningful descriptions that explain what changes were made. This is especially important in collaborative projects where others rely on your messages to understand the context of the changes.

When adding a new feature to a web application, instead of writing a vague message like “added stuff,” you could provide a more detailed description. For example:

• Actual Message: Add user authentication feature with JWT support

This message indicates exactly what was done and introduces the technology used (JWT - JSON Web Token), which informs the team about the implementation specifics.

Notes:

• Keep the message in the imperative mood (e.g., “Add” instead of “Added”) to maintain consistency across your commit history.
• Whenever possible, reference any related issues or pull requests in your message for better traceability.

Example 2: Use of Bullet Points for Multiple Changes

When you have multiple changes in a single commit, bullet points can help clarify the various updates made. This practice is particularly useful when refactoring code or addressing several issues in one go.

For instance, if you fixed several bugs in a module, instead of summarizing the changes in a single line, you could format your commit message like this:

• Actual Message: Fix bugs in user profile module
  • Corrected logic error in profile retrieval
  • Enhanced input validation for user data
  • Updated unit tests to cover new validation cases

This approach provides a clear breakdown of what was changed, making it easier for others to review the commit.

Notes:

• Consider following a consistent format for bullet points across your repository.
• Ensure that each bullet point is concise yet informative enough for others to understand the changes.

Example 3: Including Contextual Information

Sometimes, it’s beneficial to include context around why a change was made. This practice is particularly useful when addressing bugs or implementing new features that may not be self-explanatory.

For example, if you fixed a critical bug that caused the application to crash under specific conditions, your commit message could reflect that:

• Actual Message: Fix crash on user login when password field is empty
  • The application would crash if users attempted to log in without entering a password.
  • Added a check to prevent submission of an empty password field.

By including the reason for the fix, you provide clarity on the importance of the change, which can be beneficial for future reference or for anyone reviewing the commit history.

Notes:

• Always try to explain the ‘why’ behind significant changes, as it adds depth to your commit history.
• This practice can also help during code reviews, as it provides reviewers with the necessary context to evaluate the changes effectively.