Day 87 of #100DaysOfLearning

There are many people who use GitHub. I would like to ask you, are you good at writing commit logs? Are you writing proper commit logs?

GitHub's version control system and the commit log it maintains are crucial for effectively managing source code in software development projects.

Why the commit log is important when using GitHub

Tracking Changes

• The commit log provides a detailed history of all changes made to the codebase over time. Developers can review previous commits to understand what modifications were made, who made them, and why.

Collaboration

• In collaborative projects involving multiple developers, the commit log serves as a record of everyone's contributions. It helps team members stay informed about the progress and changes made by others.

Reverting Changes

• If a bug is introduced or an undesirable change is made, the commit log allows developers to easily revert the codebase to a previous stable state by referencing the relevant commit.

Code Review

• The commit log facilitates code review processes. Reviewers can examine the changes introduced in each commit, understand the context, and provide feedback or suggestions.

Documenting Progress

• Well-written commit messages act as documentation for the project's evolution. They explain the rationale behind specific changes, making it easier for developers to understand the codebase and its history.

Branch Management

• The commit log plays a crucial role in managing branches in Git. Developers can create new branches from specific commits, merge branches together, and resolve conflicts based on the commit history.

Release Management

• When preparing releases or deploying updates, the commit log helps identify the changes included in each release, making it easier to track features, bug fixes, and other modifications.

In terms of writing commit logs, it's important to follow best practices for writing clear and descriptive commit messages.

Efficient Commit Log

While the commit log is invaluable for source code management, having guidelines or rules for writing commit messages can greatly improve their effectiveness and efficiency.

Use Imperative Mood

• Commit messages should be written in the imperative mood, describing what the commit does rather than what it did. For example, "Add new feature" instead of "Added new feature."

Keep it Short but Descriptive

• The commit message's summary line should be concise (ideally under 50 characters) but descriptive enough to convey the essence of the change.

Separate Subject from Body

• If more context is needed, separate the subject from the body with a blank line. The body can provide additional details, motivation, or explanations.

Use Present Tense

• Write the commit message in the present tense, as if you are giving instructions to the codebase.

Reference Issues/Tickets

• If the commit resolves an issue or ticket, include a reference to it in the commit message (e.g., "Fix #42: Resolve login error").

Commit Related Changes

• Avoid bundling unrelated changes in a single commit. Each commit should ideally address a single logical change or task.

Follow a Standard Format

• Adopt a consistent format for commit messages within your team or project, such as the conventional commits specification or a custom format.

Use Descriptive Labels

• For larger projects, use labels or prefixes in the commit message to categorize the type of change (e.g., "fix:", "feat:", "docs:", "refactor:").

Commit Early and Often

• Make frequent, smaller commits rather than infrequent, large commits. This helps with code review, debugging, and reverting changes if needed.

Verbs for effective commit logs

This may sound like an English study, but below is a list of verbs that I think would be good to use in a commit log.

• Add
• Create
• Implement
• Introduce
• Refactor
• Rename
• Update
• Modify
• Change
• Remove
• Delete
• Fix
• Resolve
• Correct
• Improve
• Enhance
• Optimize
• Merge
• Revert
• Initialize
• Configure
• Format
• Restructure
• Reorganize
• Relocate
• Move
• Rename
• Split
• Combine
• Integrate
• Simplify
• Clarify
• Document
• Comment
• Annotate
• Lint
• Format
• Style
• Test
• Build
• Deploy
• Release

For example:

• "Add authentication module"
• "Refactor user registration flow"
• "Fix memory leak in data processing"
• "Improve performance of search algorithm"
• "Update dependency versions"
• "Merge feature branch into main"
• "Document API usage examples"
• "Test new billing functionality"

By using precise and descriptive verbs, your commit messages will clearly convey the nature of the changes made, making it easier for other developers, or your future self, to understand the commit log and the project's evolution.

The frequency and granularity of commits

The frequency and granularity of commits are important considerations when aiming to write descriptive and effective commit logs. There is no one-size-fits-all answer, as it depends on the project's complexity, team preferences, and development practices.

Commit Granularity

• It is generally recommended to make smaller, more frequent commits rather than infrequent, large commits. This approach promotes better organization, easier code review, and simpler rollbacks if needed. Each commit should ideally represent a single, logical change or feature.

Frequency of Commits

• The frequency of commits can vary based on the development workflow and the nature of the changes being made. However, it is often advisable to commit after completing a self-contained task or feature, rather than waiting until the end of the day or week.

Atomic Commits

• Strive for atomic commits, where each commit represents a complete, self-contained change. Avoid combining unrelated changes in a single commit, as this can make it difficult to understand the commit log and revert specific changes if necessary.

Task-Based Commits:

• When working on a specific task, feature, or bug fix, it can be helpful to create a commit for each subtask or logical step within that larger task. This approach provides a granular history of the changes made and facilitates easier code review and debugging.

Commit Early and Often

• It is generally better to commit more frequently than to accumulate a large number of changes before committing. Committing early and often helps prevent potential conflicts, reduces the risk of losing work, and provides a more detailed commit history.

Collaboration and Code Review

• In collaborative projects, frequent commits can aid in code review processes, allowing team members to review and provide feedback on smaller, incremental changes rather than large, monolithic commits.

Human-written commit log / Generative AI-written commit log

I believe while generative AI could potentially assist in generating commit messages based on the changes made to the code, it is generally better for developers to write their own commit logs.

1. Context and Intent: Developers have the best understanding of the context, motivations, and intent behind their code changes. Capturing this nuanced information in commit messages is crucial for effective communication and future reference.
2. Collaborative Communication: Commit logs serve as a communication channel among team members. They provide insights into the thought processes, design decisions, and rationales behind each commit. This human-to-human communication is essential for collaboration and knowledge sharing.
3. Ownership and Accountability: By writing their own commit messages, developers take ownership and accountability for their work. This sense of responsibility can contribute to better code quality and more descriptive commit messages.
4. Learning and Improvement: The process of documenting changes through well-written commit messages can be a valuable learning experience for developers. It encourages them to think critically about their code changes and communicate them effectively, which can lead to improved coding practices and better teamwork.
5. Customization and Specificity: While AI could potentially generate generic commit messages, developers are better equipped to tailor the messages to the specific project, codebase, and team conventions. They can use domain-specific terminology, reference relevant issues or tickets, and provide additional context as needed.

Generative AI could potentially assist in suggesting or improving commit messages based on the code changes, but it should be used as a supportive tool rather than a replacement for human-written commit logs. Ultimately, the developer's understanding, context, and communication skills are essential for creating meaningful and effective commit messages.

By writing their own commit logs, developers not only contribute to a clear historical record of the codebase but also facilitate better collaboration, knowledge sharing, and overall project maintenance within their teams.