Git workflow
Branch Naming conventions
Use the conventions set up by your company to keep consistent. If you are needing to come up with a standard, here are some things to keep in mind.
<type>-descriptionStart with a group name: use types such as used in commits to encapsulate the main purpose of the branch. Ideally these would be feat.
Use separators: most often developers use hyphens(-) between words rather than camelcase or other separators.
keep the name short:
Follow clean naming practices making the branch name clear and concise. Like variables, branches should be pronounceable, make meaningful distinctions, and avoid disinformation.
Unique ID
If you are using a tracking tool like DeepSource you may use a numeric ID to keep track of the branch. Using a number can make it simpler to find a specific branch since only one branch would have that number. The branch name should not be composed of only numbers.
Author name
Some companies choose to include author name in PR for tracking what people are working on.
Size
Depending on how comfortable you are with your changes you may choose to keep your commit to 3 or less files. Avoid making changes to files that affects many other files requiring you to change them as well. Strive not to repeat work. If you change the majority of a file, it will be harder to make sure the code works as expected and most likely you are addressing more than one concern.
Git Branch Naming Convention: 7 Best Practices to Follow | HackerNoon
Git Branching Naming Convention: Best Practices — {coding}Sight (codingsight.com)
Commit naming conventions
Commit names allow your reviewers to quickly understand the changes made in your commit, allowing them to merge it into the master branch faster assuming there are no bugs.
<type>[optional scope]: <description><Type>: Fixes are used when no new features are introduced but issues are resolved. Feat is the type for adding a new feature. A new feature such as adding a new library or a new component. You may also choose to use these types: Refactor type covers when a change does not effect functionality but instead changes how that functionality is achieved. Use revert when changing code back. There is also test, wip, build, docs, style, perf, chore, and ci.
[Optional scope]: Add ! for commits introducing breaking changes such as my requiring using a new version of react. You may also identify what the commit is relevant to such as api.
Description: You should be able to summarize the changes in one sentence with a clear small purpose/change. Avoid the temptation to make changes you see a need for that are irrelevant to the changes you have been making.
Squashing
To combine multiple commits into one you can squash commits when merging branches using rebase or merge. You may choose to squash commits in order to minimize the amount of commits in the master branch, however there are pros and cons to squashing.
Pros
- commit history is cleaner and easier to read and/or make sense of
- every commit is “green” and so tools like
git bisectcan be used, and any commit can be deployed with confidence - a lot of OS projects require it and so it’s a great “advanced git” skill to get good at
Cons
- It can be messy and complicated even for experienced git users
- We lose detailed history and the ability to cherry pick components
- It makes PR comment threads less readable if same branch/PR is use
- paired PRs may lead to a loss of commits for some individuals
Here is an example of squashing:
git rebase -i HEAD~3
pick 23fD3dds fix: resolve redundant error toasts
squash 4443sdFs fix: ensure one error toast
squash 3we12Aa fix: ensure correct error message appears in toastHow to Squash Commits in Git | Learn Version Control with Git (git-tower.com)
To Squash commits or not to Squash · Issue #7 · AgileVentures/AgileVentures (github.com)
Git Strategies
Github Flow
Github flow is a simple branching strategy where every branch other than master is a working branch. Each time you will branch off of master, make changes, pull request, address comments, merge pull request, and delete comments. This is a good choice for small teams.
Git Branching Strategies: GitFlow, Github Flow, Trunk Based… (flagship.io)