Git Best Practices: From Commit Syntax to Managing Issues and Milestones

Git and GitHub are tools we use to keep track of changes, collaborate with our team, and manage projects. In this post, I’ll share some simple best practices that many people overlook. We’ll cover writing clear commit messages, managing issues and milestones, and even automating workflows with commit syntax.

1. Writing Effective Commit Messages

Why Good Commit Messages Matter

Imagine this scenario: Your team lead asks you to revert a change from two weeks ago, but all your commits look like this:

- "updates"
- "fix"
- "changes"
- "final fix"
- "really final fix"

Not very helpful, right? Now compare it with more descriptive messages:

- feat(auth): add google OAuth as sign in option
- fix(ui): resolve the footer spacing
- docs: update API guide for login

The difference is clear! The second example tells you exactly what changed and where, making it much easier to track and manage your code.

Conventional Commit Syntax

Here’s the basic structure:

type(scope): description

Types you can use:

feat: New features
fix: Bug fixes
refactor: Code changes that neither fix bugs nor add features
docs: Documentation changes
chore: Routine tasks, maintenance
test: Adding or modifying tests
style: Changes that don't affect code behavior (spacing, formatting, etc.)
The scope is optional but helpful, like (ui), (api), or (auth).

Pro tip: Always use the imperative mood in your description. Write them as commands:

“add user login page” instead of “added user login page”
“fix database schema” instead of “fixed database schema”

2. Managing Issues and Milestones

Using Issues for Better Collaboration

Issues help you track bugs, tasks, or questions about your project. Think of them as smart sticky notes that can be used for:

• Feature requests
• Bug reports
• Task tracking
• Discussion threads
• Documentation improvements
• When creating an issue, include:

Title: Choose a clear, concise title.
Example: Bug: App crashes on login
Description: Explain the problem and steps to reproduce it.
Assignment: Assign the issue to the team member responsible for fixing it.

Grouping Work with Milestones

Milestones let you group related issues together to set clear project goals. For example, if you’re preparing for a new release, you might create a milestone called “version 2.0” and add all related issues under it. As each issue is closed, the milestone updates automatically to show your progress.

For example, imagine you have a set of issues for a new feature:

Issue 1: Design login page
Issue 2: Implement authentication
Issue 3: Write tests for login
Group these under a milestone called “Login feature.” As you resolve each issue, the milestone updates automatically.

3. Automating Workflows with Commit Syntax

GitHub offers some cool automation features that help keep your project organized and make collaboration easier. Here are two key features:

1. Automatically Closing Issues

When you include keywords like fixes, closes, or resolves followed by an issue number in your commit messages, GitHub will automatically close the corresponding issue once the commit is merged. This saves you from having to manually update the issue status. For example:

fix(api): resolve pointer error fixes #12

In this example, when the commit is merged, GitHub will automatically close issue #12. This ensures your project’s progress is always up to date.

2. Linking Commits and Issues

GitHub also automatically creates links between issues when you reference them. When you include an issue number (e.g., #12) in your commit message,and click on #12 in github, it’ll tak you directly to that issue. This makes it easy to trace which changes were made to resolve the issue.

4. Extra Tips for Better Git Practices

Here are a few more simple tips to help you make the most of Git:

• Commit Often: Small, focused commits make it easier to track changes and debug issues.
• Review Your Work: Before pushing your commits, take a moment to read them over. Clear and correct messages are key.
• Use Branches: Create a new branch for each feature or fix. This keeps the main branch stable and your work organized.
• Link Issues: When working on an issue, reference it in your commit messages. This builds a clear connection between the work done and the tasks or bugs. For more details on commit syntax and these automation features, check out the Git documentation and the Conventional Commits specification.

Conclusion

Good Git practices are not just about following rules but they also help you work more efficiently, communicate better with your team, and keep your project organized. By writing clear commit messages, effectively managing issues and milestones, and using automation where possible, you can greatly improve your development workflow.

Let me know if this post helps, or if you have ideas on how it can be improved!