Skip to content

git-workflow.md

Latest commit

 

History

History
139 lines (98 loc) · 4.18 KB

git-workflow.md

File metadata and controls

139 lines (98 loc) · 4.18 KB

Git Workflow for Contributors

This guide outlines the branching strategy, commit conventions, and pull request process for the project. Following this workflow ensures smooth collaboration and a clean, maintainable git history.

In This Guide

Before Writing New Code

  1. Fetch and rebase the latest changes from main while in your own branch: 
    git pull origin main
command fetches the latest commits from the main branch of the origin remote repository and rebases your current local branch on top of those changes, creating a linear commit history without merge commits

After Finishing Your Work

  1. Push your feature branch to the remote: 
    git push origin <your-feature-branch>
  2. On GitHub, open a Pull Request (compare & pull request) from your branch into main.
  3. Request reviews, address feedback, then approve and merge the PR.
  4. (Optional) Delete your feature branch once the PR is merged.

Important: Always start by syncing with the latest main to avoid conflicts, and use Pull Requests to safely merge your changes.

Best Practices

Branch Naming Convention

Use descriptive branch names that reflect the feature you're working on:

  • feature/user-authentication
  • feature/todo-crud-operations
  • bugfix/database-connection
  • setup/documentation-restructure

Commit Messages

Write clear, descriptive commit messages:

  • feat: add user registration endpoint
  • fix: resolve database connection timeout
  • docs: update API documentation
  • refactor: reorganize project structure

Before Creating a Pull Request

  1. Test your changes locally
  2. Run the application to ensure it still works
  3. Update documentation if you've changed APIs or added features
  4. Review your own code for any obvious issues

Pull Request Guidelines

  1. Provide a clear title describing what the PR does
  2. Include a description explaining the changes and why they were made
  3. Request reviews from relevant team members
  4. Respond to feedback promptly and professionally
  5. Keep PRs focused - one feature or fix per PR

Team Workflow

Main Branch Protection

  • The main branch is protected and requires:
    • Pull request reviews
    • Passing tests (when implemented)
    • Up-to-date branches

Code Review Process

  1. Author creates PR and requests reviews
  2. Reviewers examine code for:
    • Functionality and correctness
    • Code quality and standards
    • Security considerations
    • Documentation completeness
  3. Author addresses feedback and updates PR
  4. Reviewers approve changes
  5. Author or maintainer merges PR

Conflict Resolution

If you encounter merge conflicts:

  1. Fetch latest changes from main
  2. Merge main into your branch locally
  3. Resolve conflicts in your IDE or text editor
  4. Test the resolved code to ensure it still works
  5. Commit the merge and push to your branch
  6. Continue with PR process

Fixing a Bad Merge

If a buggy Pull Request is accidentally merged into main, you can safely undo it using git revert. This command creates a new commit that reverses the changes from the bad merge.

  1. Get the latest main branch.

    git checkout main
git pull origin main

  2. Find the commit hash of the bad merge. Look at the history to find the hash of the PR merge you want to revert.

    git log --oneline -n 5

  3. Revert the commit. This creates a new commit that undoes the bad one. A text editor will open for the commit message; the default is usually fine.

    # Replace <commit-hash> with the hash you found
git revert <commit-hash>

  4. Push the revert commit. This is a safe, non-destructive action that works with branch protection.

    git push origin main

Remember: Good git practices help keep the project organized and make collaboration smoother for everyone! 🚀