Notes
Programming Best Practices & Further Reading
Git & Best Practises for Projects & Teams

Git & Best Practices for Project Phase

Introduction

Version control is essential for collaborative software development. While Git is the most popular version control system, other tools like GitLab (opens in a new tab), BitBucket (opens in a new tab), Mercurial (opens in a new tab), and CVS (opens in a new tab) offer alternatives. Here, we’ll focus on Git conventions and tools that can help coordinate group projects effectively.

Commit Messages

Effective commit messages enhance project clarity and history tracking. Follow these best practices:

  • Imperative Mood: Write commit messages in the imperative mood (e.g., "Fix bug" rather than "Fixed bug"). This aligns with messages generated by Git commands like git merge and git revert.
  • Message Structure: Use a clear and concise subject line, followed by a detailed body if necessary.

Simple Commit Message:

git commit -m "Fix issue with user authentication"

Detailed Commit Message:

git commit

This will open your default text editor (often Vim (opens in a new tab)) for a more detailed message.

For enforcing commit message conventions, consider tools like Commitizen (opens in a new tab) to ensure consistency.

Branching

Branching helps manage different features and updates without disrupting the main codebase.

  • Creating a Branch:
git checkout -b feature-branch
  • Merging a Branch:
git pull origin master  # Update local master with latest changes
git checkout feature-branch
git merge master
git push origin feature-branch

  • Handling Merge Conflicts: Use git status to identify conflicts. Resolve them in your code editor (e.g., VS Code’s merge conflict interface (opens in a new tab)), then commit the resolved changes.

  • Pull Requests: Create a Pull Request on GitHub to propose merging your changes. Request reviews to ensure code quality before merging. Reviewers can comment, approve, or request changes.

  • Post-Merge Cleanup: After merging, delete the branch to keep your repository clean:

git branch -d feature-branch  # Delete branch locally
git push origin --delete feature-branch  # Delete branch on GitHub

Branch Protection

Protect your main branches to ensure code quality and stability:

  • Require Pull Request Reviews: Enable settings to require code reviews before merging.
  • Enforce Status Checks: Ensure that code passes automated tests and linting checks before merging.
  • Restrict Merge Permissions: Limit who can merge into protected branches to maintain code integrity.

Rebasing

Rebasing is an alternative to merging that can help maintain a cleaner commit history.

  • Basic Rebase Workflow:
git checkout feature-branch
git fetch origin
git rebase origin/master
  • Handling Rebase Conflicts: Resolve conflicts as you would with merge conflicts. Use git rebase --continue after resolving each conflict.

For a comparison of merging and rebasing, check out Atlassian's guide (opens in a new tab).

Enforcing Repository Rules

ESLint

Use ESLint (opens in a new tab) to maintain code quality and consistency.

  • Install ESLint:
npm install eslint --save-dev
  • Initialize ESLint:
npx eslint --init
  • Choose a Style Guide: Popular options include Airbnb’s style guide, especially for React projects. Adjust rules as needed.

Git Hooks with Husky

Husky (opens in a new tab) enables you to add Git hooks to enforce rules before commits and pushes.

  • Install Husky:
npm install husky --save-dev
npx husky install
npm set-script prepare "husky install"
  • Create Pre-commit Hook:
npx husky add .husky/pre-commit "npm test"
  • Add Multiple Scripts:
npx husky add .husky/pre-commit "npm test && eslint ./ --fix"

This setup ensures that tests and linting checks pass before allowing commits.

By adhering to these practices, you’ll maintain a high-quality codebase and streamline your development process, especially in collaborative environments.

Additional Resources

Agile Development & Communication WorkshopProject Management & Pitches