3

1.5) GitHub Guidelines

Darklighter edited this page 2025-02-26 23:37:21 +00:00

Table of Contents

• 1.5) GitHub Guidelines

1.5) GitHub Guidelines

Disclaimer: We do not demand that you behave strictly according to this guideline. This is more a help for newcomers to understand the GitHub workflow better.

When committing changes in GitHub Desktop, it's essential to write clear and effective commit messages. These messages serve as a record of what changes have been made and why. Writing consistent and useful summaries helps both you and your collaborators understand the context of the changes, making it easier to track the history of a project.

Here are the key rules and best practices for writing commit summaries in GitHub Desktop:

1. Write a Short, Clear Summary

Keep it concise: The summary (or commit message title) should be brief—ideally under 50 characters.

Describe the change: Clearly state what was changed. Avoid vague messages like "Fixed stuff" or "Changes made."

Example:
Good: "Fix bug in login form validation"
Bad: "Fixed stuff"

2. Use the Imperative Mood

Write in the imperative tone: Use verbs in the present tense, as if you're giving a command. This is the standard for commit messages in Git.

Example:
Good: "Update README with new setup instructions"
Bad: "Updated README with new setup instructions"

The imperative mood aligns with the idea that a commit is an action to be applied to the codebase.

3. Capitalize the First Letter

Capitalize the first letter of your commit message summary to make it consistent and professional.

Example:
Good: "Add new feature to handle user input"
Bad: "add new feature to handle user input"

4. Leave the Description Optional

Use the description field sparingly: The commit description provides space for more detailed information about the change. While this is optional, it should be used to explain the "why" behind the change, not just the "what."

Add context: If the change is complex or addresses a specific issue, include additional details in the description. For example, describe why you made the change or how it improves the codebase.

Example:
Commit Summary: "Fix authentication issue with OAuth"
Description: "Resolved issue where the OAuth token was not being stored correctly, leading to authentication failures for users."

5. Use Bullet Points for Multiple Changes

If your commit contains multiple changes, you can use bullet points in the description to make it easier to read.
 
Example:

Commit Summary: "Refactor login system"
Description:
Refactored user authentication logic.
Improved error handling for failed login attempts.
Updated unit tests for new authentication flow.

6. Be Specific and Descriptive

Be specific about the changes: If you're fixing a bug, adding a feature, or refactoring code, be specific about what was modified and how it impacts the project.

Example:
Good: "Fix image upload issue on mobile devices"
Bad: "Fix bugs"

7. Avoid Large, Unfocused Commits

Focus each commit on one change: A commit should ideally contain a single logical change, like fixing a bug, adding a feature, or refactoring a part of the codebase. Large commits that combine unrelated changes make it harder to understand the history of the project.

Example:
Good: "Add unit tests for user registration module"
Bad: "Add unit tests and refactor login page"

8. Refer to Issues or Pull Requests

If your commit addresses an open issue or references a pull request, include the issue number in the commit message (using # followed by the issue number).

Example:
Good: "Fix issue #45: Resolve crashing issue on app startup"
Bad: "Fix crashing issue"

9. Avoid Personal or Ambiguous Messages

Avoid using personal pronouns like "I" or "We" in commit messages.

Commit messages should be professional and clearly communicate the change to other team members.

Example:
Good: "Refactor data processing function"
Bad: "I refactored the data processing function"

10. Keep it Relevant to the Codebase

Commit messages should always be relevant to the changes made in the code. Don't use commit messages for unrelated updates, like changes to the documentation, unless the commit is specifically related to that task.

Example:
Good: "Update CSS styling for homepage buttons"
Bad: "Update README"

Example of a Good Commit Message:

Commit Summary: "Add search bar functionality to the homepage"
Description:
Implemented search bar for better user experience.
Linked search functionality to the backend API.
Updated front-end to handle dynamic search queries.