Git Contribution Guide

git-contribution-guide.md

Branches

• At first create a master branch for yourself with your name like ali/master
• Keep your branch names short, easy to read, and meaningful. Other developers should be able to understand a branch's contents by reading its name.
• Specify a scope for your branch, a branch should not introduce 5 features and fixes 4 bugs at the same time
• Keep your branch updated, merge master into your master branch from time to time. An updated branch is easier to review and far more easier to merge.
• Make sure that your desired branch name does not have conflict with any remote branches.
• Always make sure that your source branch is up-to-date with the remote server before creating a new branch from it.
• Never push commits directly to the master unless it's necessary.
• Don't use rebase unless it's necessary, use merge instead. Although you are allowed to use rebase before pushing your changes for the first time.
• Push your changes to remote branch from time to time. Preferably at the end of the day, before you leave.

To achieve the mentioned requirements, use the following format for naming your branches:

• Name your branches in this format: <type>/<name>
• type can be one of these items:
  • feat introduces a new feature
  • bug fixes a bug, or a set of related bugs
  • hotfix fixes a small yet critical bug, should have 1 or at most 2 commits
  • refactor applies refactoring on the code base
  • chore neither introduces a new feature nor fixes a bug. use this prefix when you want to change configuration options, names, or similar situations
• name
  • should be short(30 chars max), yet meaningful
  • use - for separating words in the name. e.g., driver-availability-log

Take a look at some examples:

# Good
feat/paid-at-destination-notification
chore/add-new-ga-keys

# Bad
CleanUp
feat/add-flag
bug/some-issues

Commits

• Write the summary line and description of what you have done in the imperative mode, as if you were commanding someone ("Add feature" not "Added feature")
• Keep your commit summary line under 100 chars
• Always leave the second line blank
• Don't end the summary line with period, it's a summary.
• If summarizing your changes in the summary line seems difficult, it's maybe because your commit includes multiple changes, commit your changes frequently to prevent this situation.
• If your commit refrences a Jira issue, mention it in the description not the summary line.
• Please use Sublime Merge and add all your changes to stage section and review all changes always & every time, to ensure that you aren't adding "wrong changes" to the commit, like commented-out codes or prints added for debugging, or changes that need separate commits.
• If you need to use "... and ..." in your commit message, it's just a red flag, and you should probably break it to two or more commits.
• Don't use vague, meaningless messages like "improve assign" or "make alarms better". we know you're not here to "degrade" or "make things worse", so explain exactly what you've done.
• After you wrote message, ask yourself: "when somebody calls git blame on these files, will my commit message help him to find the reason that this change is introduced?" if your answer is negative, try to rewrite the message.

To achieve the mentioned requirements, use the following format for your commit messages:

• <type>(<scope>): <message>
  • <type> can be one of these items:
    • build changes that affect the build system, external dependencies, or composer-packages
    • docs documentation only changes
    • feat a new feature
    • bug a bug fix
    • refactor a code change that neither fixes a bug nor adds a feature
    • chore changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc). For example fixing linitng issues
    • test adding missing tests or correcting existing tests
    • temp never use this type, it can only be used by the person who is in charge of the deployments.
  • <scope> can be one of these items, based on your project:
    • global changes that affect multiple scopes, for example removing an unused utility function from multiple apps.
    • The scope is a dependent proejct's like Fulfilment, Financial, Delivery and so on.
  • <message>
    • Should be short, meaningful, expressive, and easy to read
    • May contain Jira issue card's link. Mentioning issue card's link helps other developers to find a code that fixes a specific issue. If you like, you can mention issue ID in the description instead of summary.
    • Capitalize first letter
    • As mentioned before, don't use period at the end of the message
    • As mentioned before, use the imperative, present tense
    • This article can help you in writing a good commit message

Take a look at some examples:

# Good
feat(tracking): Add TripSettlement model
bug(supply): Fix the position of PDF export button of the accounting panel

# Bad
Add model
feat(tracking) add some models
bug(sale): Fix issue
feat(core): Add TripFinancials, TripSettlement, and TripDetails models and bbq a chicken