GitHub Flow.md

GitHub Flow Introduction

GitHub Flow is a collaborative development workflow advocated by GitHub. It promotes a branching strategy that emphasizes frequent pull requests (PRs) for code reviews and seamless merging.

Key Points:

• Feature Branches: Developers create feature branches from the main branch (often called master or main) to work on new features or bug fixes.
• Pull Requests (PRs): Developers submit PRs to propose changes from their feature branches to the main branch.
• Code Reviews: Team members review the PR code and provide feedback.
• Merge or Close: Based on reviews, the PR is merged into the main branch (or closed if changes are not needed).

Pros:

• Simplified Branching: Easy-to-understand branching structure fosters collaboration.
• Early and Frequent Reviews: Catches issues early through frequent PRs.
• Integration-Friendly: Designed for seamless integration with GitHub's features like PRs and code reviews.
• Faster Releases: Enables faster releases by merging reviewed changes often.

Cons:

• Conflicts on Main Branch: Frequent merges can lead to merge conflicts if not managed carefully. Note that, the GitHub PR mechanism is the best UI to solve such merge conflict problems, better than most of the UI tools.
• Less Suitable for Large Teams: Managing numerous feature branches can become complex in large teams, which normally use git cli directly.
• Discipline Required: Requires team members to adhere to the branching strategy for it to work effectively.

Overall, GitHub Flow is a lightweight and efficient workflow ideal for small to medium-sized teams working on projects with frequent updates. However, it might require some adjustments for larger teams or projects with a stricter release cycle.

GitHub Flow In Practice

Here's a breakdown of the core steps involved in GitHub Flow:

1. Create a Branch:

• Start by navigating to the repository you want to work on.
• Click "New Branch" to create a new branch from the main branch (usually named master or main).
• Use a descriptive branch name that reflects the changes you'll make (e.g., fix-login-bug, add-user-feature). This helps others understand your work's purpose.

2. Make Changes:

• With your new branch checked out locally, make your desired modifications to the codebase.
• This can involve adding new features, fixing bugs, or refactoring existing code.
• Test your changes thoroughly to ensure they function as intended and don't introduce unintended side effects.
• Having made changes on your branch locally, push them to the remote to reflect the updates when ready.

3. Create a Pull Request (PR):

• Once your changes are complete and tested, head back to GitHub.
• Click "Pull Requests" and initiate a new PR.
• Provide a clear and concise description of the changes you've made in the PR description.
• This description helps reviewers understand the context and rationale behind your modifications.
• Include relevant details like bug fixes addressed, new features added, or changes made.

4. Code Reviews and Collaboration:

• Once your PR is submitted, assign reviewers from your team who are familiar with the codebase or the area you've modified.
• Encourage discussion and provide opportunities for feedback.
• Address comments and suggestions from reviewers promptly. These comments may highlight areas for improvement, potential issues, or alternative approaches.
• You can make further changes on your branch locally and push them to the PR to reflect the updates.

5. Merge or Close the PR:

• After addressing feedback and ensuring the changes are approved, you can merge the PR into the main branch. This integrates your work into the main codebase.
• Alternatively, if the PR isn't ready or needs further work, you can close it. This can happen if changes are deemed unnecessary, require more iterations, or don't align with project goals.

6. Delete the Branch:

• Once your PR is successfully merged, we should delete the feature branch, it's optional but recommended, else we all need to pull in this unnecessary branch whenever we update our local repo.
• Since the changes are now part of the main branch, the feature branch is no longer necessary.
• FTA, in terms to keep feature branches for historical purposes (or as a reference point for future work) the deleted feature branch can be restored.

Additional Tips:

• Use clear and descriptive commit messages throughout your development process. These messages help reviewers understand the incremental changes you've made.
• Consider using smaller, focused PRs for easier review and merging. This breaks down large changes into more manageable chunks.
• Maintain an active discussion around code reviews and provide constructive feedback in a collaborative manner.
• Always use the git-rebase method when pull in new changes from the remote git repo.
• To minimize the merge conflicts, especially when we're making changes to the same file on top of each other,
  • do a git pull to refresh local repo before pushing to the remote.
  • react quickly to the review request, this is critical when we're making changes to the same file on top of each other. Else, if the PRs are approved out of the order when they're initially lined up, it'll introduce big chaos and headaches to all other related PRs.

By following these steps and best practices, you can leverage GitHub Flow to streamline collaboration, ensure code quality, and deliver changes efficiently.

For further details, please check out the official GitHub Flow document.