Commit message best practices

From binaryoption
Jump to navigation Jump to search
Баннер1
  1. Commit Message Best Practices

This article details the best practices for writing commit messages when using a version control system like Git, as commonly integrated with MediaWiki. Clear and informative commit messages are crucial for maintaining a healthy and understandable project history, facilitating collaboration, and simplifying debugging. These principles apply whether you’re contributing to the core MediaWiki codebase, an extension, or a skin.

Why are Good Commit Messages Important?

Consider your commit history as a project's memory. Future developers (including your future self!) will rely on it to understand *why* changes were made, not just *what* changes were made. Poorly written commit messages can lead to:

  • **Difficulty understanding the codebase:** Trying to decipher the intent behind changes without a clear message is time-consuming and frustrating.
  • **Debugging nightmares:** When tracking down the source of a bug, commit messages can provide valuable clues about when and why a problematic change was introduced.
  • **Collaboration challenges:** A shared understanding of the project's evolution is essential for effective teamwork. Vague messages hinder this understanding.
  • **Reduced code review quality:** Reviewers need context to effectively assess changes. Good commit messages provide that context.
  • **Automated Tooling Issues:** Many automated tools (release notes generation, changelog creation, blame, bisect) rely on well-formatted commit messages to function correctly.

The Anatomy of a Good Commit Message

A good commit message typically consists of the following parts:

1. **Subject Line:** A concise summary of the change (maximum 50 characters). 2. **Blank Line:** Separates the subject line from the body. *Crucially important*. 3. **Body:** A more detailed explanation of *why* the change was made, *what* the change does, and any potential side effects. This can span multiple paragraphs. 4. **Footer (Optional):** Information about related issues, breaking changes, or co-authors.

Let's break down each part with examples tailored to a MediaWiki context.

1. The Subject Line

The subject line is the most important part of the commit message. It should be:

  • **Concise:** Aim for 50 characters or less. This ensures it displays well in various Git tools.
  • **Imperative Mood:** Use the imperative mood ("Fix bug," not "Fixed bug" or "Fixes bug"). Think of it as completing a sentence that starts with "If applied, this commit will…". For example: "Add unit test for ParserHook" rather than "Added unit test for ParserHook."
  • **Specific:** Avoid vague terms like "Update," "Fix," or "Changes." Instead, describe *what* is being updated or fixed.
  • **Capitalized:** Start with a capital letter.
  • **No Period:** Do not end the subject line with a period.
    • Examples:**
  • **Good:** "Refactor: Improve performance of category listing"
  • **Good:** "Fix: Prevent XSS vulnerability in user profile"
  • **Good:** "Add: New skin option for customizing sidebar"
  • **Bad:** "Updated files"
  • **Bad:** "Fixed a bug"
  • **Bad:** "Changes to the database"

2. The Blank Line

This seemingly insignificant line is vital. It separates the subject line from the body, allowing Git tools to correctly parse the message. Without it, the entire message may be treated as the subject line. This is a common mistake!

3. The Body

The body provides more context and detail about the commit. It should answer the following questions:

  • **Why was this change made?** What problem does it solve? What motivated the change? Referencing a Bugzilla ticket number is highly recommended.
  • **What does this change do?** Describe the specific changes made and how they address the problem.
  • **Are there any side effects?** Are there any potential drawbacks or compatibility issues?
  • **How was this tested?** Describe the testing process used to ensure the change is correct.

The body should be written in complete sentences and paragraphs, using proper grammar and spelling. Wrap lines at 72 characters for readability in various environments.

    • Example:**

``` Fix: Prevent XSS vulnerability in user profile

This commit addresses a potential cross-site scripting (XSS) vulnerability in the user profile page. Specifically, the user's "About me" field was not properly sanitized, allowing malicious JavaScript code to be injected and executed in other users' browsers.

The fix involves encoding the user's "About me" field using htmlspecialchars() before it is displayed on the page. This ensures that any potentially harmful characters are escaped.

This change has been tested by:

  • Manually entering malicious JavaScript code into the "About me"
   field and verifying that it is not executed.

Related: Bugzilla ticket #12345 ```

4. The Footer (Optional)

The footer can be used to provide additional information, such as:

  • **References to Issue Trackers:** "Related: Bugzilla ticket #12345" or "Refs: #12345"
  • **Breaking Changes:** "BREAKING CHANGE: This commit introduces a breaking
   change to the API.  Users will need to update their code to be
   compatible."
  • **Co-authors:** "Co-authored-by: John Doe <[email protected]>" (useful for collaborative work)
  • **Cross-references to other commits:** "See commit abcdefg for related changes."
    • Example:**

``` Refactor: Improve performance of category listing

This commit refactors the code responsible for generating category listings to improve performance. The previous implementation was inefficient due to repeated database queries.

The new implementation caches the category data in memory, reducing the number of database queries required. This results in a significant performance improvement, especially for categories with a large number of articles.

This change has been tested by:

  • Measuring the page load time for category pages before and after
   the change.

BREAKING CHANGE: The category listing API has been changed. Users who rely on the previous API will need to update their code.

Refs: Bugzilla ticket #56789 ```

Common Mistakes to Avoid

  • **Vague Subject Lines:** "Fix bug," "Update code," "Changes."
  • **Missing Blank Line:** The space between the subject and body is *required*.
  • **Long Subject Lines:** Keep them under 50 characters.
  • **Non-Imperative Mood:** "Fixed," "Fixes," "Updating."
  • **Lack of Context:** Failing to explain *why* the change was made.
  • **Ignoring Line Length:** Wrap lines at 72 characters for readability.
  • **Committing Work-in-Progress:** Commit only complete, logical units of change. Use staging area effectively. Avoid committing "fix typo" or "minor changes" without context.
  • **Committing Large Changes:** Break down large changes into smaller, more manageable commits.

Tools to Help

Commit Message Conventions

While the above guidelines are generally accepted, specific projects may have their own conventions. It's important to familiarize yourself with the conventions used in the project you're contributing to. Common conventions include:

Further Resources

Start Trading Now

Sign up at IQ Option (Minimum deposit $10) Open an account at Pocket Option (Minimum deposit $5)

Join Our Community

Subscribe to our Telegram channel @strategybin to receive: ✓ Daily trading signals ✓ Exclusive strategy analysis ✓ Market trend alerts ✓ Educational materials for beginners

Баннер
Retrieved from "https://binaryoption.wiki/index.php?title=Commit_message_best_practices&oldid=37899"