You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+36-36Lines changed: 36 additions & 36 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,48 +9,48 @@ I listed 10 rules for having a professional commit message.
9
9
10
10
### 1. Meaningful messages:
11
11
12
-
The first and most important rule for a Git commit message is this! Each commit message must have a complete, meaningful and independent description. Commit message has to be valuable for its readers. As a reader, when I looked at the Git's log of your repository, All the commits messages must be clear for me and I be known about the changes of each commit, just by a simple looking!
12
+
The first and the most important rule for a Git commit message is this! Each commit message must have a complete, meaningful and independent description. Commit message has to be valuable for its readers. As a reader, when I'm looking at the Git's log of your repository, All the commit messages must be clear for me and I should be aware about the changes of each commit, just by a simple look!
13
13
14
14
I prepared some examples of bad commit messages and I explained why they are bad, so look at these:
15
15
16
16
17
17
❌ `First commit`
18
18
19
19
🔷 **Why it's bad?**
20
-
> It's not important for the reader to be known about the number of commit in its message. Because he/she can be known about it, by has a looking to the Git's log. Also he/she couldn't have any idea about the what happen's in the codebase in this commit!
20
+
> It's not important for the reader to know about the number of commits in its message. Because he/she can be aware about it, by a looking to the Git's log. Also he/she can't have any idea about what's happening in the codebase in this commit!
21
21
22
22
❌ `Add some codes`
23
23
24
24
🔷 **Why it's bad?**
25
-
> When you works on a codebase, you can **add**, **delete** or **modify** the codes and there is not any other option! So, it has not any benefit for the reader! You must say what you added!
25
+
> When you work on a codebase, you can **add**, **delete** or **modify** the code and there is no any other options! So, it has not any benefits for the reader! You must say what you added!
26
26
27
27
❌ `Refactoring and cleaning codes`
28
28
29
29
🔷 **Why it's bad?**
30
-
> How can I be informed that which section of the codebase had been modified? Or how can I guess what type of refactoring had been applied on codebase? Your commit message have to include the answer of these questions in self!
30
+
> How can I be informed that which section of the codebase has been modified? Or how can I guess what type of refactoring has been applied on the codebase? Your commit message have to include the answer of these questions in self!
31
31
32
32
❌ `Bug resolved`
33
33
34
34
🔷 **Why it's bad?**
35
-
> Which bug is resolved? Have to the reader guess the bug?! Of course no, so please explain what bug is resolved explicitly.
35
+
> Which bug is resolved? must the reader guess the bug?! Of course not, so please explain which bug is resolved explicitly.
36
36
37
37
❌ `I added a new feature`
38
38
39
39
🔷 **Why it's bad?**
40
-
> According to the previous examples, here we haven't any clear vision about the modifications of codebase! Btw, there is no need to use pronoun at the first of this commit message. Git saves that who is the author of each commit by self and we haven't do a duplicated action!
40
+
> According to the previous examples, here we haven't any clear vision about the modifications of the codebase! Btw, there is no need to use pronoun at the first of this commit message. Git saves the author of each commit by itself and we haven't to do a duplicated action!
41
41
42
42
43
43
### 2. Neither Long nor Short:
44
44
45
-
If you want to write a meaningful message for a commit, avoid writing lengthy descriptions. Very summarized texts too! A sign of a good commit message is a suitable length most of the time. Maybe you want to know why we should avoid long/short messages in commit messages? Well, here's an example.
45
+
If you want to write a meaningful message for a commit, avoid writing lengthy descriptions. Very summarized texts too! A sign of a good commit message is a suitable length most of the time. Maybe you want to know why we should avoid long/short messages in our commit messages? Well, here's an example.
46
46
47
47
Assume my friend asks me to lend him some money.
48
48
49
-
❌ `Please lend me money!`
50
-
> It's an example of a short message. When my friend tells it, I ask two pertinent questions: "How much money do you need?" and "When will you get it back?". He could make me clear about them, so there was no need to these questions.
49
+
❌ `Please lend me some money!`
50
+
> It's an example of a short message. When my friend tells it, I ask two related questions: "How much money do you need?" and "When will you get it back?". He could make me clear about them, so there was no need to these questions.
51
51
52
52
❌ `Hey Ahmad, get on the bus as soon as it arrives at the bus station. Then go to your bank, fill out a form, and then get the money from the bank and lend me $20. I'm going to return it in three weeks.`
53
-
> This is an example of a long message. It's an example of a long message. Don't tell me how I can provide some money! Just tell me your request.
53
+
> This is an example of a long message. It's an example of a long message. Don't tell me how can I provide some money! Just tell me your request.
54
54
55
55
✅ `Ahmad, please lend me 20 dollars. I will return it in 3 weeks.`
56
56
> Perfect! It's that I want to hear!
@@ -67,25 +67,25 @@ When you want to write a commit message, suppose you give Git an order. Do not a
67
67
68
68
For example, suppose you implemented a function that can transform the characters of a text into the upper case characters.
69
69
70
-
❌ `Implementing a function that transform letters to upper case.`
70
+
❌ `Implementing a function that transforms letters to upper case.`
71
71
72
-
❌ `I added a function to transforming letters to upper case.`
72
+
❌ `I added a function to transform letters to upper case.`
73
73
74
-
❌ `A function to transforming letters to upper case has been added.`
74
+
❌ `A function that transforms letters to upper case has been added.`
75
75
76
76
✅ `Implement a function to transform letters to upper case.`
77
77
78
78
79
79
### 4. Avoid Writing Details:
80
80
81
-
This rule complements the `Neither Long nor Short` rule. No need to write everything and details.
82
-
Remember always, you must tell `What` and `Why` something added/removed/modified in the codebase, not `How`! Also, no need to write the bit or low-priority modifications.
81
+
This rule complements the `Neither Long nor Short` rule. No need to write everything in details.
82
+
Always remember, you must tell `What` and `Why` something added/removed/modified in the codebase, not `How`! Also, no need to write the bit or low-priority modifications.
83
83
84
-
For example, assume you want to refactor a function named getUser in your codebase. After refactoring it, you notice that the related file has an unused variable inside itself, so you decide to remove it. When you want to commit your changes, there is no need to write something like this:
84
+
For example, assume you want to refactor a function named getUser in your codebase. After refactoring it, you may notice that the related file has an unused variable inside of itself, so you decide to remove it. When you want to commit your changes, there is no need to write something like this:
85
85
86
86
❌ `Refactor the 'getUser' function and delete an unused variable in its related file.`
87
87
88
-
Why is it not necessary to refer to the delete variable? Because it wasn't the primary goal of this commit. It was a minor modification that we could fix along with another commit. Of course, you can delete this unused variable in a separate commit, or maybe you want to make a new task for your project to find all unused variables and remove them all in a commit!
88
+
Why it's not necessary to refer to the delete variable? Because it wasn't the primary goal of this commit. It was a minor modification that we could fix along with another commit. Of course, you can delete this unused variable in a separate commit, or maybe you want to make a new task for your project to find all unused variables and remove them all in a commit!
89
89
90
90
I prefer this one:
91
91
@@ -98,55 +98,55 @@ This one is an optional offer for your commit messages but can make them very re
98
98
99
99
Here is a list of the most usable prefixes that I often see in software teams:
100
100
101
-
*`[BUGFIX]`: For resolving any bug and issue from the codebase.
101
+
*`[BUGFIX]`: For resolving any bug and issues from the codebase.
102
102
*`[TEST]`: For writing any type of tests (Unit / End-to-End / UserStory / Integration / Regression / ...)
103
103
*`[FEATURE]`: For adding a new feature and implementation
104
104
*`[REFACTOR]`: For improving current codes for any purpose like better readability, performance, etc.
105
105
*`[UPDATE]`: For updating libraries and dependencies, also updating current features by documentation.
106
106
*`[BASE]`: For installing new libraries and dependencies and setting up the infrastructures of the codebase, like configuring the project and its packages.
107
107
*`[DOCS]`: For adding or modifying the documentations.
108
108
109
-
The above cases are only some offers for you so, there isn't any force to using them. You can have your own!
109
+
The above cases are only some offers for you so, there isn't any force to use them. You can have your own!
110
110
111
111
🔑 *The text of your prefixes can be lowercase. Please follow a fixed rule. For example, if you want to write your prefixes in lowercase, write them all in lowercase forever in the related repository.*
112
112
113
113
114
114
### 6. Emoji? Please No!
115
115
116
-
Recently I'm seeing developers use emojis in commit messages. In my opinion, it's not a good practice! Say Why? Because of two reasons:
116
+
Recently I've seen developers using emojis in their commit messages. In my opinion, it's not a good practice! Say Why? Because of two reasons:
117
117
118
-
*That they don't have a clear message.
119
-
* Emojis have specific Unicode, maybe we have a terminal that doesn't support those Unicode, so we can't see any emoji in our terminal.
118
+
*They don't have a clear message.
119
+
* Emojis have specific Unicode, maybe we have a terminal that doesn't support those Unicode, so we can't see any emojis in our terminal.
120
120
121
-
One of my colleagues disagreed with me about case one. She believed that each emoji has a special meaning, and we can use them in our commit messages. I asked her to give an example. She showed the emoji of a worm (🐛) and said that everybody knows that this emoji refers to a bug! I asked her what should be used for features, refactoring, testing, and ...? She introduced a website to me and said they provide lots of emojis and have a unique meaning for all of them.
121
+
One of my colleagues disagreed with me about the case one. She believed that each emoji has a special meaning, and we can use them in our commit messages. I asked her to give an example. She showed the emoji of a worm (🐛) and said that everybody knows that this emoji refers to a bug! I asked her what should be used for features, refactoring, testing, and ...? She introduced a website to me and she said they provide lots of emojis and have a unique meaning for all of them.
122
122
123
123
It's the address of that website: [Gitmoji](https://gitmoji.dev)
124
124
125
-
I disagree with my colleague because this website is not a reference for git commits! It's not the product of a famous company with high-level standards! Only one tasteful person has presented some emojis and has written explanations for each of them according to his taste. That and no more!
125
+
I disagree with my colleague because this website is not a reference for git commits! It's not the product of a famous company with high-level standards! Only one tasteful person has presented some emojis and has written explanations for each of them according to his taste. And nothing more!
126
126
One day, if terminals support showing images, I can create a website for using images in the commit messages! For example, I can provide the picture of a scared man and say that refers to a bug! It's not standard :)
127
127
128
128
129
129
### 7. Referral Prefixes:
130
130
131
-
This case is similar to `Conceptual Prefixes` with a main different: The *Conceptual Prefixes* have a straight and clear messages for their reader and directly say their content. But the *Referral Prefixes* point to a external description, like a task on Jira, a card on Trello, an issue on Gitlab or anything else! *Referral Prefixes* usually be used in the large teams and teams that they used Scrum methodology.
131
+
This case is similar to `Conceptual Prefixes` with a main difference: The *Conceptual Prefixes* have a straight and clear message for their readers and they directly say their content. But the *Referral Prefixes* point to a external description, like a task on Jira, a card on Trello, an issue on Gitlab or anything else! *Referral Prefixes* usually be used in the large teams and teams that they use Scrum methodology.
132
132
133
-
For using a referral prefix, there are some common styles that I list:
133
+
For using a referral prefix, there are some common styles that I listed:
134
134
135
135
*`[#<CARD-NUMBER>]`, `[#<ISSUE-NUMBER>]` or `[#<TASK-NUMBER>]`
136
136
*`[<CARD-NUMBER>]`, `[<ISSUE-NUMBER>]` or `[<TASK-NUMBER>]`
137
137
*`(<CARD-NUMBER>)`, `(<ISSUE-NUMBER>)` or `(<TASK-NUMBER>)`
138
138
139
139
140
-
An examples of the above cases:
140
+
As an example of the above cases:
141
141
142
-
*`[#217] Resolve the bug of 'fetchUsers' function that causes some users be missed`
142
+
*`[#217] Resolve the bug of 'fetchUsers' function that causes some users to be missed`
143
143
144
-
> [#217]at the first of this commit can refer to task number 217. It's no matter what tasks manager you are using. You can always use these referral prefixes to point to your tasks/cards/issues.
144
+
> [#217] the first part of this commit can refer to a task number 217. It's no matter which tasks manager you are using. You can always use these referral prefixes to point your tasks/cards/issues.
145
145
146
146
147
-
🔑 *You can use both **Conceptual Prefixes** and **Referral Prefixes** together. It relates to your decision.*
147
+
🔑 *You can use both **Conceptual Prefixes** and **Referral Prefixes** together. It is related to your decision.*
148
148
149
-
I list examples of usage of conceptual prefixes and referral prefixes side each other:
149
+
I listed some examples for the usage of conceptual prefixes and referral prefixes side by side:
150
150
151
151
152
152
*`[#REFACTOR](217) Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase`
@@ -156,12 +156,12 @@ I list examples of usage of conceptual prefixes and referral prefixes side each
156
156
*`[#217][REFACTOR] Use Array's methods like 'forEach' and 'map' instead of simple 'for' and 'while' loops in the codebase`
157
157
158
158
159
-
🔑 *The above examples are just some template and they are not a rule. You can use them in any other styles.*
159
+
🔑 *The above examples are just some template and they are not some rules. You can use them in any other styles.*
160
160
161
161
162
162
### 8. Separate References to The Codes and Specialized Terms
163
163
164
-
Sometimes commit messages to contain references to variables, functions, methods, classes, and specialized terms. Whenever you need to write a specialized term or the name of a variable/function/method/class or anything similar, wrap its name in a couple of backticks or quotation marks. It helps the reader detect that the wrapped word is different from others and is a reference to the codebase.
164
+
Sometimes commit messages contain references to variables, functions, methods, classes, and specialized terms. Whenever you need to write a specialized term or the name of a variable/function/method/class or anything similar, wrap its name in a couple of backticks or quotation marks. It helps the reader detect that the wrapped word is different from the others and there is a reference to the codebase.
165
165
166
166
167
167
❌ `Upgrade Jest and React Testing Library to the latest versions`
@@ -190,15 +190,15 @@ Sometimes commit messages to contain references to variables, functions, methods
190
190
✅ `Write integration test for 'Settings' module`
191
191
192
192
193
-
* Wrap lines at 72 characters. (Always there exist exceptions)
193
+
* Wrap lines at 72 characters. (Always there exists some exceptions)
194
194
195
195
* Don't use urls in the messages.
196
196
197
197
### 10. Have a Coherent Log!
198
198
199
-
If you have a tour in the log of lots of the famous repositories, you can see a lot of differences between commit messages. For example, some of them have prefixes, and some don't. Some of them include emojis, some of them no. Some start with a capitalized letter, some of them no, etc. It usually happens because teams and persons don't follow typical rules. Always have a complete and clear guideline for yourself and your team. By doing it, you can prevent having inconsistent commit messages.
199
+
If you have a tour in the log of lots of the famous repositories, you can see a lot of differences between commit messages. For example, some of them have prefixes, and some other have'nt. Some of them include emojis, some of them no. Some start with a capitalized letter, some of them no, etc. It usually happens because teams and people don't follow typical rules. Always have a complete and clear guideline for yourself and your team. By doing it, you can prevent having inconsistent commit messages.
200
200
201
201
You can use some external tools and linters for double-checking the commits. Linters and these external tools, ensure that no commit message will conflict with the rules you applied. They force you and your team members to follow the rules.
202
202
203
203
204
-
**If this repository helped you, don't forgive getting a star ;)**
204
+
**If this repository helped you, don't forgive getting a star ;)**
0 commit comments