Best Practices for Updating Feature Branches with Merging and Rebasing

Keeping Your Feature Branch Up to Date

Avoid rebasing or merging just for the sake of it. Only do it when necessary. The smaller your pull requests (PRs), the less likely you’ll encounter conflicts that require merging.

Many teams require that everything be up-to-date with the main branch before merging a PR, and GitHub will help you with this.

If you need to rebase or merge with the upstream branch, you'll need to choose between rebasing or merging. To avoid complications, make merging your default option.

• Rebase If you have only a few commits (or none) and haven’t pushed your branch to GitHub yet, rebasing will work well. You'll pull the latest version of the main branch and replay your changes on top of it. Be mindful of potential conflicts—consider using an "interactive rebase" to address these.

• Merging If you are working on a feature branch and need to incorporate the latest changes from main or develop, merging is often easier. Just be aware that the commits will be in an unexpected order.

Rebase Process

1. Commit any changes in your feature branch.
2. Checkout the branch to rebase from (usually develop).

   git checkout develop
   git pull

3. Switch back to your feature branch.

   git checkout <feature-branch-name>
   git rebase origin/develop
   git push origin <feature-branch-name> --force

Merge Process

1. Checkout develop and pull the latest changes.

   git checkout develop
   git pull

2. Checkout your feature branch.

   git checkout <feature-branch-name>
   git merge develop

3. Resolve any merge conflicts before pushing.

   git push origin <feature-branch-name>

Important Notes:

• After a rebase, pushing your changes requires the --force flag because it alters Git history. If others are working on the same branch, coordinate with them to avoid disruptions. They will need to delete and re-checkout your branch after a force push.
• Merging main or develop into your feature branch is often simpler, but be prepared for the commit order to be different from what you expect.

Summary

• Work on feature branches created from develop.
• Name branches following the GitHub issue number and description.
• Use GitHub Issues to track tasks, features and bugs with the provided issue template.
• Use the provided PR template when creating pull requests.
• Merge feature branches into develop via PRs.
• Keep your feature branch up to date by merging or rebasing.
• Merge develop into main via a PR when ready for release.
• Create a GitHub release describing the merged changes.

Following this workflow ensures a smooth development process with a clear path from development to production.