Repository navigation
Expand file tree
/
Copy pathreadme.html
More file actions
194 lines (194 loc) · 17 KB
/
Copy pathreadme.html
File metadata and controls
194 lines (194 loc) · 17 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
<h1 id="git-flow-based-tutorial">Git-flow based tutorial</h1>
<p>This is a small guide to help you getting started using git in a team environment.<br />
It is targeted at people having small to medium experience with git.</p>
<!-- TOC -->
<ul>
<li><a href="#git-flow-based-tutorial">Git-flow based tutorial</a>
<ul>
<li><a href="#purpose-of-this-document">Purpose of this document</a></li>
<li><a href="#foreword">Foreword</a></li>
<li><a href="#1-principles">1. Principles</a>
<ul>
<li><a href="#11-saving-your-progress">1.1. Saving your progress</a></li>
<li><a href="#12-branching">1.2. Branching</a></li>
</ul></li>
<li><a href="#2-how-tos-in-normal-development">2. How-tos in normal development</a>
<ul>
<li><a href="#21-starting-a-feature">2.1. Starting a feature</a></li>
<li><a href="#22-working-on-a-feature">2.2. Working on a feature</a></li>
<li><a href="#23-getting-updates-from-others">2.3. Getting updates from others</a></li>
<li><a href="#24-switching-between-features">2.4. Switching between features</a></li>
<li><a href="#25-finishing-a-feature">2.5. Finishing a feature</a></li>
<li><a href="#26-reviewing-a-feature">2.6. Reviewing a feature</a></li>
<li><a href="#27-merging-a-feature">2.7. Merging a feature</a></li>
<li><a href="#28-deleting-merged-branch">2.8. Deleting merged branch</a></li>
</ul></li>
<li><a href="#3-how-tos-in-release-process">3. How-tos in release process</a>
<ul>
<li><a href="#31-starting-release">3.1. Starting release</a></li>
<li><a href="#32-finishing-release">3.2. Finishing release</a></li>
<li><a href="#33-starting-hotfix">3.3. Starting hotfix</a></li>
<li><a href="#34-finishing-hotfix">3.4. Finishing hotfix</a></li>
</ul></li>
<li><a href="#useful-references">Useful references</a></li>
</ul></li>
</ul>
<!-- /TOC -->
<h2 id="purpose-of-this-document">Purpose of this document</h2>
<p>Git is a very flexible tool which allows a lot of operations.<br />
That is why during the years several possible workflows appeared.<br />
Whatever workflow (or their combination) a team is using, it should be fully defined.</p>
<p>The purpose of this document is to define such a flow.</p>
<h2 id="foreword">Foreword</h2>
<p>Below is a proposal of how to use git in a project.<br />
It is based on best practices, originating from classical methods of working with git.<br />
We are not going to go into too many details, but we hope to provide enough information so that the process can be understood and followed.</p>
<p>If you are interested, feel free to have a look at some more <a href="#useful-references">useful references</a>!<br />
Also, do not hesitate to ask colleagues for help. They will be happy to help you with this topic! And if you learn something new, do not hesitate to share it with others or to update this document!</p>
<p>The first section of this document covers the main <a href="#1-principles">Principles</a> of using git.<br />
Once you understand the principles, we will explain specific actions for specific situations in the <a href="#2-how-tos-in-normal-development">How-tos</a> section.</p>
<h2 id="principles">1. Principles</h2>
<p>This section describes principles of using git.</p>
<h3 id="saving-your-progress">1.1. Saving your progress</h3>
<p>The process of saving your current changes is very similar in any workflow. You are most likely already familiar with it, but here is a small refresher:</p>
<ol type="1">
<li><p>You make changes.<br />
After you made some changes and you think that you achieved some milestone which you want to save, procede to the next step. Don’t be shy about saving your work in git often - doing it often for each logical step helps you to manage your progress and to easily “go back in time”. It is quite okay to do up to several commits per hour.</p></li>
<li><p>Select (also known as <em>add</em> or <em>stage</em>) the changes which you want to save now.<br />
Maybe you changed several things - for example you added a new model and also optimized some effects in an entirely different part of the project. If this is the case, select only one related part of your changes - for example only the model or only the effects.</p></li>
<li><p><em>Commit</em> your changes. This saves your changes locally, so your curent progress is secure! If you have more changes which logically are separate pieces of the project, repeat steps 2 and 3 again. This will make it easier for you and your team to see what was done, to conduct review and to merge changes with their own.</p></li>
<li><p><em>Push</em> your commit to the server. If you want to back up you changes online, you <em>push</em> them. You should do this to make your changes visible to your team, or to be able to continue working on another computer, or just to back up your progress because you don’t trust your hard drive.</p></li>
</ol>
<h3 id="branching">1.2. Branching</h3>
<p>Using branches - various versions of history - is one of the most powerful features of git. Over the years, best practices of using branches were formed into so-called git workflows. These git workflows can be very efficient, if used correctly. Therefore it is very important that a team fully defines how branches are used and follows these rules, to get the most out of git.</p>
<p>This part will describe a proposed way of using branches based on some of these best practices, especially the git flow principle (see <a href="#useful-references">useful references</a>).</p>
<p>The following best practices are important:</p>
<ol type="1">
<li><em>Feature-branch approach</em><br />
It means that for every specific self-consistent feature which requires more than one commit (see <a href="#11-saving-your-progress">1.1. Saving your progress</a>, point 3), a separate branch should be created.<br />
This approach has many benefits:</li>
</ol>
<ul>
<li>possible to share only desired changes, and not all changes which you have done. It allows doing several tasks at the same time.<br />
</li>
<li>easy to switch to another task if something is not working. Even one person can work on several tasks at the same time, and it is not a problem if one task can not be finished - just leave that feature-branch alone until the time is right (for example when you know how to finish it, or if someone else finished something which you needed, or simply when you have enough time to continue working on it)</li>
<li>easy to find changes contributing to this feature later, in case we need to check how something was done</li>
<li>easy to review</li>
<li>this approach is scalable (regardless of how many people are in your team)</li>
</ul>
<ol start="2" type="1">
<li><p><em>Using development branch</em><br />
Additionally to feature branches, a so-called development branch should be used. Whenever some feature is finished, it should be merged into the development branch. Whenever a new feature is started, it should be started at the top of development branch.</p></li>
<li><p><em>4-eyes principle</em><br />
It is a good idea if the feature branch is merged into development branch not by the feature branch author, but by someone else (reviewer). If there is a clear team leader, it can be done by him/her. If there is not, it can be done by a member who can understand/check this particular feature branch.</p></li>
<li><p><em>Merge only into development</em><br />
This principle defines that whenever a feature is completed, it is merged <em>only</em> into development branch and never into any other branches.</p></li>
<li><em>Start from top of development branch, keep up-to-date</em> Feature branches should be started from the top of development branch. Feature branches should also be rebased on top of it.<br />
This approach allows to have a very healthy easy-to-use history, rather when unhealthy history when people are merging branches randomly. Compare:<br />
-<img src="./Docs/images/HealthyGitGraph.jpg" title="Healthy git graph" alt="healthy" />-<img src="./Docs/images/UnhealthyGitGraph.jpg" title="Unhealthy git graph" alt="unhealthy" /><br />
Of course, you don’t have to rebase your branch on development every time someone’s feature is merged. You do it only in the following cases:</li>
</ol>
<ul>
<li>you are finished with the feature branch. In this case you rebase it on top on development and request somebody to merge it</li>
<li>you need that feature to continue with your feature</li>
<li>you anticipate conflicts and want to solve them as early as possible</li>
<li>you just want to be up-to-date with your colleagues work</li>
</ul>
<ol start="4" type="1">
<li><p><em>Keep branches small</em><br />
Usually it is a good idea to keep branches relatively small, because it is simple to merge/rebase/review them. Almost any big feature can be separated into smaller features and thus smaller branches.</p></li>
<li><em>Naming convention for branches</em><br />
It is practical to name branches consistently. Git allows grouping branches by <em>group/branch</em> name notation. The most common approach which we strongly recommend is using this:</li>
</ol>
<ul>
<li>feature/nameOfFeature for features</li>
<li>bugfix/nameOfBugfix for bugfixes during development</li>
<li>hotfix/nameOfHotfixes for hot fixes on a release version</li>
<li>release/v_xx_yy_zz for performing minor changes to get the release up and running</li>
</ul>
<p>If the team works with any tool which has tasks (Trello, Jira, TFS etc.) it is also a good idea to add an ID of the task to the branch name. For example, if in Trello you have a card ID 131 (by default IDs in trello are hidden, but it is easy to show them), in which you say you want to make a splash screen, you create a new branch: feature/131_SplashScreen</p>
<p>Doing so provides traceability, which allows to use git for finding code and even implementation history for specific features!</p>
<h2 id="how-tos-in-normal-development">2. How-tos in normal development</h2>
<p>This section describes what actions you should take in which situation, effectively fully defining the workflow.</p>
<p>Since different people might use different GUIs, this tutorial just names an action and provides a git command. If you cannot find appropriate action in your GUI of choice (SourceTree, GitKraken, Tower, GitExtensions etc.), don’t hesistate to ask the team or Google!</p>
<p>In this section you will notice that using the feature-branch aproach makes branch operations very intuitive, because what you do with a feature - you also do with a branch!</p>
<h3 id="starting-a-feature">2.1. Starting a feature</h3>
<p>If you want to start a new feature, you<br />
1) pull development branch<br />
<code>git checkout development</code><br />
<code>git pull</code><br />
2) create a new branch at the tip of development branch<br />
<code>git checkout -b feature/id_featureName</code><br />
Naturally id and featureName are your own, like 131_SplashScreen.</p>
<h3 id="working-on-a-feature">2.2. Working on a feature</h3>
<p>You just keep adding and committing your changes, making your branch grow!<br />
We assume that you are familiar with these operations. If you are not, don’t hesitate to ask your team mates or Google!</p>
<h3 id="getting-updates-from-others">2.3. Getting updates from others</h3>
<p>Fetch the changes from others to see who is doing what.<br />
<code>git fetch --all --prune</code></p>
<p><code>--prune</code> here deletes branches which do not exist anymore on the server.</p>
<p><strong>Important:</strong> do not merge changes of others directly, as stated in <a href="#12-branching">1.2. Branching</a> !</p>
<p>Rather, if you feel that you need to get synchronized, rebase your branch on development branch:</p>
<p><code>git checkout development</code><br />
<code>git pull</code><br />
<code>git checkout feature/id_featureName</code> <code>git rebase development</code></p>
<p>This way the content you get will be more stable compared to merging branches from others directly! In addition, the branch history will be clean and easy to use.</p>
<h3 id="switching-between-features">2.4. Switching between features</h3>
<p>If you want to work on some other feature, just switch a branch. If it is a new feature, make a new branch just like explained above. Otherwise, just switch branches:<br />
<code>git checkout feature/anotherId_anotherFeatureName</code></p>
<h3 id="finishing-a-feature">2.5. Finishing a feature</h3>
<p>When you are done with a feature, rebase it on development and push it to the server. You can also push it more often as a back up or to work on a different computer.</p>
<p><code>git rebase development</code><br />
<code>git push</code></p>
<h3 id="reviewing-a-feature">2.6. Reviewing a feature</h3>
<p>At this point you probably want your feature to get merged into development. It is a good idea to let someone else do that for you, because it implies a review. There are different ways to let a reviewer know that you want your feature merged: * create a pull request in your git website (BitBucket, GitHub, etc.)<br />
It is especially useful for big features, because in websites like BitBucket you can comment and discuss the feature changes. It will also help you and your team to find these discussions at a later point in time. * via chat or any other communication tool * by using a naming convention. For example, you add a prefix <code>merge/</code> to your branch like this:</p>
<p><code>git branch -m whateverName merge/whateverName</code></p>
<p>If you want a particular person to review your change, you can also specify that in the name, for example:</p>
<p><code>git branch -m whateverName merge/reviewerName/whateverName</code></p>
<p><em>But in most cases, it is better if one pre-defined person is responsible for merging branches into development!</em></p>
<h3 id="merging-a-feature">2.7. Merging a feature</h3>
<p>Once you are happy with the changes in the branch, peform a merge:</p>
<p><code>git checkout development</code><br />
<code>git merge feature/id_Name --no-ff</code></p>
<p>“–no -ff” here means no fast forward or <em>always create a merge commit</em>. So effectively you always get a commit which aggregates the whole feature. This way, when the branch is deleted, it allows you to still find it with the commit name and to check either aggregated changes, or commit by commit.</p>
<h3 id="deleting-merged-branch">2.8. Deleting merged branch</h3>
<p>After merging, the branch can be deleted. It can be done with:</p>
<p><code>git push -d branchName</code> to delete the branch on the server<br />
<code>git checkout development</code> to go back to development branch before deleting feature branch locally<br />
<code>git branch -d branchName</code> to delete feature branch locally</p>
<p>The reviewer has to delete both local (if he created it) and remote branches. For the author, it is enough to delete only local branch (remote one is deleted by reviewer). Others should only have remote branches, e.g. origin/branchName, so running <code>git fetch --all --prune</code> as described above will automatically delete all branches which are not on the server anymore.</p>
<h2 id="how-tos-in-release-process">3. How-tos in release process</h2>
<h3 id="starting-release">3.1. Starting release</h3>
<p>Whenever we feel like creating a release, we create a branch release/numberOfRelease. On this branch we do bugfixes and fine-tuning for the release. This allows developers who are not involved in the release to keep working on their features.</p>
<h3 id="finishing-release">3.2. Finishing release</h3>
<p>Once we are happy with the status, we can merge this release branch into the master branch and create a tag with the version number. This is an official release version!</p>
<p>Also it is a good idea to merge back into development, so that all of our fine-tuning becomes accessible to everybody.</p>
<h3 id="starting-hotfix">3.3. Starting hotfix</h3>
<p>Whenever a hotfix is needed, i.e. we found a bug in a release and need to update but we don’t want to test all new features, we create a hotfix branch from master branch and do our hotfix there.</p>
<h3 id="finishing-hotfix">3.4. Finishing hotfix</h3>
<p>Once we are happy with the hotfix, we merge it back to master and… done! Of course then we merge master branch into development as well to make our fix accessible to the whole team.</p>
<h2 id="useful-references">Useful references</h2>
<p>Original article on git flow<br />
http://nvie.com/posts/a-successful-git-branching-model/</p>
<p>Git cheat-sheets<br />
https://www.git-tower.com/blog/git-cheat-sheet/<br />
https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet<br />
https://ndpsoftware.com/git-cheatsheet.html</p>
<p>Atlassian description of the workflows:<br />
https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow<br />
https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow</p>
<p>Git main site<br />
https://git-scm.com/</p>
<p>Git reference<br />
https://git-scm.com/docs</p>
<p>Git Pro book, most comprehensive manual on git<br />
https://git-scm.com/book/en/v2</p>
<p>Git glossary<br />
https://mirrors.edge.kernel.org/pub/software/scm/git/docs/gitglossary.html</p>
<p>List of git guis<br />
https://git-scm.com/downloads/guis</p>
<p>Couple of presentations from me on Git:<br />
https://github.com/Nochdarus/GitKnowHow</p>
<p>Nice web-based presentation on Git:<br />
https://github.com/agross/git-reveal</p>