The gitworkflows(7)
illustrated
by K. Tateishi
(@ktateish)
What’s gitworkflows?
A set of workflows used in the Git project itself.
Details are described in the online manual
gitwork...
Why gitworkflows?
● You can push -f for integration branches
● You can merge topic branches casually
● You can keep master...
In these slides
I’ll show you how gitworkflows* work with
simple commit graphs.
It helps you to understand gitworkflows ev...
There is an initial commit.
Let’s start from here.
master
This is the ‘master’ branch
This is the ‘master’ branch
Say you need three topics (A, B, C) for the first release.
A
B
C
Grow them...
A
B
C
And they’ve done.
Integrate to master?
No. ‘master’ can’t be reset after topics once merged
(and pushed to public repositories).
Use a ‘throw-away’ integration b...
‘pu’ is the name of the throw-away integration branch.
Stands for ‘Proposed Update’
pu
‘pu’ should be branched from the tip of the most advanced
non-throw-away branch.
‘master’ would be fine at this time.
(You...
Merge topic A…
(checkout pu and merge topic-A. You can use --
no-ff merge like below if you want)
merge
Merge topic A, B...
merge
Merge topic A, B and C into ‘pu’.
merge
Then, let’s do tests especially about interactions among the
merged topics/features. (They can’t be tested on each
branch)
BTW you can push ‘pu’ to public repositories if needed.
(push origin pu)
e.g. a CI server is watching a public repository ...
You may find some bugs/lacks of functionalities on ‘pu’
with integrated state of the three topics.
One of them was introduced on topic A
So fix it on that topic.
commit
Others should be added/fixed on each branch.
commit
And merge them into ‘pu’?
No.
‘pu’ is a throw-away integration branch.
So reset ‘pu’ to ‘master’
(checkout pu and reset --hard master)
reset
So reset ‘pu’ to ‘master’ so that throw away the old ‘pu’.
(checkout pu and reset --hard master)
And then, re-do merges...
merge
And then, re-do merges...
merge
And then, re-do merges...
merge
Now you’ve got new ‘pu’ that cleanly merged three
topics.
Note that all developers involved including you can’t work
on ‘pu’. All topics have to be forked off from ‘master’
Without reset, resulting branch / commit graph would be little
more complicated, even though they have identical trees.
tr...
OK. Let’s push new ‘pu’ to public repositories and test it.
You have to do push -f origin pu or push origin
+pu if you’ve pushed old ‘pu’ before, because new ‘pu’ isn’t
direct descen...
After test, you found that two features from topic A, B were
good and stable but one from topic C wasn’t.
You decide to merge topic A and B into ‘master’ because
they are stable enough.
Merge topic A…
(checkout master and merge topic-A)
merge
Merge topic A and B into ‘master’.
merge
# Now topic A, B are not important any more for these slides.
# So gray out them.
At the same time, a bug on topic C was spotted and fixed.
Let’s rebuild ‘pu’.
commit
‘pu’ should be reset to ‘master’ again.
(checkout pu and reset --hard master)
reset
Resetting ‘pu’ also means that throwing away the old
‘pu’.
And then...
Merge topic C, then push ‘master’ and ‘pu’.
Again, you have to use forced push for ‘pu’, so you may say:
git push origin m...
You want more time to stabilize topic C.
So you decide to make the first release with two features
already merged into ‘ma...
For making release, tag an annotated tag ( ) at ‘master’
tag
v1.0.0
The release tag name is ‘v1.0.0’
Then push it.
(tag -a ‘v1.0.0’ master and push origin v1.
0.0)
tag
v1.0.0 was released.
v1.0.0
You received new topics created after release. They
would be branched from ‘master’.
new topics
Some new topics would be good but some are possibly
not good (i.e. break something).
So new topics should be merged into ‘pu’ first.
merge
Merge another topic into ‘pu’ and push it.
merge
You find two of three active topic branches look good
after tests. But you are unsure for...
Good
Good
Unsure for: - Stability of the implementation
- Excellence of the design
- Requirement of the feature
etc.
It means that keeping them in ‘pu’ is tiring because they
won’t be changed for a while, but merging them into
‘master’ can...
In other words, you need an integration branch for
stabilizing, testing or previews for those topics.
‘next’ is the integration branch for such use. It’s like a
hybrid of throw-away and non throw-away. You can
reset ‘next’ w...
‘next’ will be branched from ‘master’.
(branch next master)
Merge the remaining old active topic, C…
(checkout next and merge topic-C)
merge
And merge new one, say topic D.
merge
Here, ‘pu’ always should be branched from the most
advanced non-throw-away integration branch.
So let’s rebuild ‘pu’ on ‘next’ at this time.
(checkout pu and reset --hard next)
reset
Old ‘pu’ will be deleted.
And then...
Merge the remaining new topic, say topic E.
merge
Then, push ‘next’ and ‘pu’
(push origin next +pu)
Note that you and developers involved cannot work on
‘next’ because it sometimes get reset. So all feature
branches should...
What are the differences between ‘next’ and ‘pu’?
‘pu’ is easily disposable but ‘next’ isn’t.
For example, if a topic merged only to ‘pu’ have a bug and
fixed on it ...
commit
Then, simply reset ‘pu’ to ‘next’...
(checkout pu and reset --hard next)
reset
And merge new tip of that topic.
(i.e. rewind and reconstruct ‘pu’)
merge
On the other hand, if a topic kept in ‘next’ have another
commit...
commit
‘next’ can’t be reset, so just merge new tip of that topic
on current ‘next’...
Like this.
merge
And rebuild ‘pu’ on new ‘next’
reset and
merge
Note that you can merge the new branch head of topic D
into ‘pu’ first if needed.
(e.g. it has too large impact to merge i...
Here is another situation.
You got new topic (say F).
You found a topic kept in ‘pu’, topic E, was totally broken
and the topic developer can’t fix it right away. When it
happe...
Reset ‘pu’....
reset
And merge again only good branches.
merge
If the broken branch was rebased with fixes after a
while...
rebased
rebased
topic
Merge the rebased new branch into ‘pu’
rebased merge
If you find a branch kept in ‘next’, e.g. topic C, is broken
and it can’t be fixed for a while...
Broken
You should revert the whole branch
(revert -m 1 <merge commit>)
revert
revert commit
reverted
merge
Of course you should rebuild ‘pu’ and push them.
reset and
merge
After a while, when the topic C was fixed all bugs rebasing
it...
rebased
Merge it into ‘next’...
merge
And rebuild ‘pu’, then push ‘next’ and ‘pu’.
reset and
merge
Again, note that ‘next’ shouldn’t be reset easily like ‘pu’.
When you want to redo something on ‘next’, just revert or re-...
But ‘next’ can be reset with announcements for involved
developers when it get awfully dirty with a number of revert
and d...
And you’ll also have chances to reset ‘next’ after feature
release. It will be shown later.
Let’s keep developing for the ...
When you think topics merged into ‘next’ are stable / having
good design / etc. you can merge them into ‘master’
Good enou...
When you think topics merged into ‘next’ are stable / having
good design / etc. you can merge them into ‘master’
Good enou...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features
required for the next feature release are merged into
‘maste...
These merges in ‘pu’ -> ‘next’ -> ‘master’ order,
downstream-ward propagation of features, are called
‘graduate’.
Unfortunately sometimes even topics merged into ‘master’
have bugs.
Fix them on their topics? No.
a bug found
Once a topic merged into ‘master’, it will be regarded as
‘master’ itself. So fix branches should be created on
‘master’ f...
Merge it into (‘pu’ and) ‘next’ first.
merge
reset and merge
Then merge it into ‘master’ if it looks good.
merge
Note that you can merge the fix branch into ‘master’ directly
when the commits in fix branch are trivial.
fix-branch for t...
Note that you can merge the fix branch into ‘master’ directly
when the commits in fix branch are trivial.
merge
But after that, don’t forget to merge ‘master’ into ‘next’ for
the fix will be included in ‘next’
(‘next’ must have the bu...
There is another situation for fixing bugs.
If the release v1.0.0 have a bug, how should we address it?
a bug found
Fix it on ‘master’ and let v1.0.0 users upgrade to ‘master’?
But some v1.0.0 users don’t want to use new features
merged i...
So you want a new integration branch only for bug fixing.
‘maint’ is such a branch. It will be branched from the latest
fe...
The fix branch have to be branched from ‘maint’.
Don’t branch from ‘master’ or any upstream.
fix-branch for the bug
If you branch the fix branch for ‘maint’ from ‘master’...
*WRONG*
fix-branch for the bug
*WRONG*
When the fix branch merged into ‘maint’, additional topics
are also merged into ‘maint’. Those downwards merging will
brea...
You can handle this case by cherry-pick the commit into
‘maint’, but you should take care where you fork off from.
cherry-...
So the fix branch should be forked off from ‘maint’.
As a general rule, fork off topics from the oldest integration
branch...
Basically merge the fix branch for ‘maint’ into ‘next’ (or ‘pu’)
first as usual because ‘maint’ never get reset.
merge
res...
Then merge it into ‘maint’ when it looks good on ‘next’.
merge
But...
Of course you can merge fix branches directly into ‘maint’
when they are trivial.
merge
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
Sometimes you should merge ‘maint’ into ‘master’, and
merge ‘master’ into ‘next’ for propagation of the fixes.
Periodic up...
When some fixes accumulated in ‘maint’, publish a fix-
release.
Tag v1.0.1 on ‘maint’ for the fix-release and push it.
v1.
0.1
tag
Well, after a while you want to make a new feature-release.
And you want have a code-freeze period for this release.
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
merge f...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fix...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
To freeze your code, just stop merging feature topics and
only merge fix-topics, including ‘maint’, into ‘master’.
fix
fea...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
You can merge feature topics into ‘next’ for integration of
them while ‘master’ is frozen. So you don’t have to stop
devel...
The code-freeze period has done. Now you will make
feature-release.
Before tagging, make sure ‘maint’ is fully merged into
‘master’ by git merge maint on ‘master’. If not merged,
some fixes ...
Now release it. Tag v1.1.0 on ‘master’ for the feature-
release and push it.
tag
v1.
1.0
New release has done. But you have some tasks for the
‘next’ and ‘maint’ after feature-release
Let’s do for ‘next’.
At first reset ‘next’ to ‘master’
reset to
master
leave a tag for in
case messed up
Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
merge active
branches
Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
merge active
branches
Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
check diff for
making sur...
Then merge active topics they weren’t included in the last
release. (And rebuild ‘pu’ if needed)
rebuild pu
This rewind and reconstruction of ‘next’ is for cleaning up the
history of it. Actually you can do this anytime with an
an...
This rewind and reconstruction of ‘next’ is for cleaning up the
history of it. Actually you can do this anytime with an
an...
Next, let’s see about ‘maint’
The task for ‘maint’ is simple. Just fast-forward ‘maint’ to
‘master’.
Fast-Foward
to master
This is done by git merge --ff-only master on
‘maint’. If it fail, the last release is missing some fixes
because ‘maint’ ...
If you merge ‘maint’ into ‘master’ before the release like
already shown, the fast-forward will succeed.
Note that if you want keep maintenance branch for the
previous feature-release, you can leave another maint
branch, e.g. m...
After the feature-release, repeat the same workflows
already shown. This is the gitworkflows(7). Keep on
developing with i...
Conclusion (1/2)
● Use throw-away integration branch like pu
● Merge topics into the throw-away(TA) first
● Test in TAs be...
Conclusion (2/2)
● Don’t base your work on pu or next
● Fork off topics from the oldest integ-branch
which the topics will...
See also
● gitworkflows(7)
● Documentation/SubmittingPatches
in Git source tree
● MaintNote in ‘todo’ branch of git.git
● ...
Q and A
Q: What is the difference between next and pu?
A: It depends.
gitworkflows(7) saids pu, throw-away, is for testing the
int...
Q: Do I have to keep {‘pu’, ‘next’, ‘maint’}
A: No, you don’t.
Just create and keep them if you need. But I recommend you
...
Q: Do I have to keep so many topics?
A: Yes.
You have to keep them until they’ve been merged into
‘master’ or ‘maint’
But ...
Q: Do I have to merge a single branch repeatedly?
A: Yes.
When you become tired of resolving identical conflicts,
enable g...
Q: May I use GitHub pull requests with gitworkflows?
A: Yes, of course.
For the git.git, GitHub pull requests are simply i...
Thank you
Upcoming SlideShare
Loading in...5
×

The gitworkflows(7) illustrated

1,022

Published on

gitworkflows(7) is a set of workflow used by git.git.
These slides will show you how it works with simple commit graphs.

Published in: Software, Technology
0 Comments
26 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
1,022
On Slideshare
0
From Embeds
0
Number of Embeds
7
Actions
Shares
0
Downloads
24
Comments
0
Likes
26
Embeds 0
No embeds

No notes for slide

The gitworkflows(7) illustrated

  1. 1. The gitworkflows(7) illustrated by K. Tateishi (@ktateish)
  2. 2. What’s gitworkflows? A set of workflows used in the Git project itself. Details are described in the online manual gitworkflows(7) shipped with Git.
  3. 3. Why gitworkflows? ● You can push -f for integration branches ● You can merge topic branches casually ● You can keep master stable with clear history ● Scalable to a large number of developers You know you can freely modify your commits and topic branches with Git. You can do it for integration branches with gitworkflows.
  4. 4. In these slides I’ll show you how gitworkflows* work with simple commit graphs. It helps you to understand gitworkflows even though they are little complicated. Here we go. * Maybe slightly different from actual workflows used by git.git, because these slides are based on my interpretation of the gitworkflows(7).
  5. 5. There is an initial commit. Let’s start from here.
  6. 6. master This is the ‘master’ branch
  7. 7. This is the ‘master’ branch
  8. 8. Say you need three topics (A, B, C) for the first release. A B C
  9. 9. Grow them... A B C
  10. 10. And they’ve done. Integrate to master?
  11. 11. No. ‘master’ can’t be reset after topics once merged (and pushed to public repositories). Use a ‘throw-away’ integration branch instead.
  12. 12. ‘pu’ is the name of the throw-away integration branch. Stands for ‘Proposed Update’ pu
  13. 13. ‘pu’ should be branched from the tip of the most advanced non-throw-away branch. ‘master’ would be fine at this time. (You may use git branch pu master)
  14. 14. Merge topic A… (checkout pu and merge topic-A. You can use -- no-ff merge like below if you want) merge
  15. 15. Merge topic A, B... merge
  16. 16. Merge topic A, B and C into ‘pu’. merge
  17. 17. Then, let’s do tests especially about interactions among the merged topics/features. (They can’t be tested on each branch)
  18. 18. BTW you can push ‘pu’ to public repositories if needed. (push origin pu) e.g. a CI server is watching a public repository for running automated tests and you want to push for it.
  19. 19. You may find some bugs/lacks of functionalities on ‘pu’ with integrated state of the three topics.
  20. 20. One of them was introduced on topic A So fix it on that topic. commit
  21. 21. Others should be added/fixed on each branch. commit
  22. 22. And merge them into ‘pu’? No. ‘pu’ is a throw-away integration branch.
  23. 23. So reset ‘pu’ to ‘master’ (checkout pu and reset --hard master) reset
  24. 24. So reset ‘pu’ to ‘master’ so that throw away the old ‘pu’. (checkout pu and reset --hard master)
  25. 25. And then, re-do merges... merge
  26. 26. And then, re-do merges... merge
  27. 27. And then, re-do merges... merge
  28. 28. Now you’ve got new ‘pu’ that cleanly merged three topics.
  29. 29. Note that all developers involved including you can’t work on ‘pu’. All topics have to be forked off from ‘master’
  30. 30. Without reset, resulting branch / commit graph would be little more complicated, even though they have identical trees. trees of these two commits are identical - with reset - without reset
  31. 31. OK. Let’s push new ‘pu’ to public repositories and test it.
  32. 32. You have to do push -f origin pu or push origin +pu if you’ve pushed old ‘pu’ before, because new ‘pu’ isn’t direct descendant of the old ‘pu’ on origin.
  33. 33. After test, you found that two features from topic A, B were good and stable but one from topic C wasn’t.
  34. 34. You decide to merge topic A and B into ‘master’ because they are stable enough.
  35. 35. Merge topic A… (checkout master and merge topic-A) merge
  36. 36. Merge topic A and B into ‘master’. merge
  37. 37. # Now topic A, B are not important any more for these slides. # So gray out them.
  38. 38. At the same time, a bug on topic C was spotted and fixed. Let’s rebuild ‘pu’. commit
  39. 39. ‘pu’ should be reset to ‘master’ again. (checkout pu and reset --hard master) reset
  40. 40. Resetting ‘pu’ also means that throwing away the old ‘pu’.
  41. 41. And then...
  42. 42. Merge topic C, then push ‘master’ and ‘pu’. Again, you have to use forced push for ‘pu’, so you may say: git push origin master +pu (prefix ‘+’ for the branch name means forced push.) merge
  43. 43. You want more time to stabilize topic C. So you decide to make the first release with two features already merged into ‘master’.
  44. 44. For making release, tag an annotated tag ( ) at ‘master’ tag
  45. 45. v1.0.0 The release tag name is ‘v1.0.0’ Then push it. (tag -a ‘v1.0.0’ master and push origin v1. 0.0) tag
  46. 46. v1.0.0 was released. v1.0.0
  47. 47. You received new topics created after release. They would be branched from ‘master’. new topics
  48. 48. Some new topics would be good but some are possibly not good (i.e. break something).
  49. 49. So new topics should be merged into ‘pu’ first. merge
  50. 50. Merge another topic into ‘pu’ and push it. merge
  51. 51. You find two of three active topic branches look good after tests. But you are unsure for... Good Good
  52. 52. Unsure for: - Stability of the implementation - Excellence of the design - Requirement of the feature etc.
  53. 53. It means that keeping them in ‘pu’ is tiring because they won’t be changed for a while, but merging them into ‘master’ can’t be done because they may be changed or possibly deleted.
  54. 54. In other words, you need an integration branch for stabilizing, testing or previews for those topics.
  55. 55. ‘next’ is the integration branch for such use. It’s like a hybrid of throw-away and non throw-away. You can reset ‘next’ with an announcement for developers, but don’t do it so frequently. next tag
  56. 56. ‘next’ will be branched from ‘master’. (branch next master)
  57. 57. Merge the remaining old active topic, C… (checkout next and merge topic-C) merge
  58. 58. And merge new one, say topic D. merge
  59. 59. Here, ‘pu’ always should be branched from the most advanced non-throw-away integration branch.
  60. 60. So let’s rebuild ‘pu’ on ‘next’ at this time. (checkout pu and reset --hard next) reset
  61. 61. Old ‘pu’ will be deleted.
  62. 62. And then...
  63. 63. Merge the remaining new topic, say topic E. merge
  64. 64. Then, push ‘next’ and ‘pu’ (push origin next +pu)
  65. 65. Note that you and developers involved cannot work on ‘next’ because it sometimes get reset. So all feature branches should be forked off from ‘master’
  66. 66. What are the differences between ‘next’ and ‘pu’?
  67. 67. ‘pu’ is easily disposable but ‘next’ isn’t.
  68. 68. For example, if a topic merged only to ‘pu’ have a bug and fixed on it ... commit
  69. 69. Then, simply reset ‘pu’ to ‘next’... (checkout pu and reset --hard next) reset
  70. 70. And merge new tip of that topic. (i.e. rewind and reconstruct ‘pu’) merge
  71. 71. On the other hand, if a topic kept in ‘next’ have another commit... commit
  72. 72. ‘next’ can’t be reset, so just merge new tip of that topic on current ‘next’...
  73. 73. Like this. merge
  74. 74. And rebuild ‘pu’ on new ‘next’ reset and merge
  75. 75. Note that you can merge the new branch head of topic D into ‘pu’ first if needed. (e.g. it has too large impact to merge into ‘next’) merge into ‘pu’ first (+ push and test) if it looks good, then merge into ‘next’ reconstruct ‘pu’. this is identical graph shown in previous page
  76. 76. Here is another situation. You got new topic (say F).
  77. 77. You found a topic kept in ‘pu’, topic E, was totally broken and the topic developer can’t fix it right away. When it happened, just reconstruct ‘pu’ ignoring broken branches. Broken
  78. 78. Reset ‘pu’.... reset
  79. 79. And merge again only good branches. merge
  80. 80. If the broken branch was rebased with fixes after a while... rebased rebased topic
  81. 81. Merge the rebased new branch into ‘pu’ rebased merge
  82. 82. If you find a branch kept in ‘next’, e.g. topic C, is broken and it can’t be fixed for a while... Broken
  83. 83. You should revert the whole branch (revert -m 1 <merge commit>) revert revert commit reverted merge
  84. 84. Of course you should rebuild ‘pu’ and push them. reset and merge
  85. 85. After a while, when the topic C was fixed all bugs rebasing it... rebased
  86. 86. Merge it into ‘next’... merge
  87. 87. And rebuild ‘pu’, then push ‘next’ and ‘pu’. reset and merge
  88. 88. Again, note that ‘next’ shouldn’t be reset easily like ‘pu’. When you want to redo something on ‘next’, just revert or re- merge instead.
  89. 89. But ‘next’ can be reset with announcements for involved developers when it get awfully dirty with a number of revert and duplicate merges.
  90. 90. And you’ll also have chances to reset ‘next’ after feature release. It will be shown later. Let’s keep developing for the second release for now.
  91. 91. When you think topics merged into ‘next’ are stable / having good design / etc. you can merge them into ‘master’ Good enough to be merged into ‘master’
  92. 92. When you think topics merged into ‘next’ are stable / having good design / etc. you can merge them into ‘master’ Good enough to be merged into ‘master’
  93. 93. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ new topic
  94. 94. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ merge
  95. 95. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ good enough for master
  96. 96. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ merge
  97. 97. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ good enough for next
  98. 98. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ merge reset and merge
  99. 99. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ new topic
  100. 100. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ merge
  101. 101. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ good enough for next
  102. 102. Repeat ‘pu’ -> ‘next’ -> ‘master’ cycle until enough features required for the next feature release are merged into ‘master’ merge reset and merge
  103. 103. These merges in ‘pu’ -> ‘next’ -> ‘master’ order, downstream-ward propagation of features, are called ‘graduate’.
  104. 104. Unfortunately sometimes even topics merged into ‘master’ have bugs. Fix them on their topics? No. a bug found
  105. 105. Once a topic merged into ‘master’, it will be regarded as ‘master’ itself. So fix branches should be created on ‘master’ for bugs of ‘master’. fix-branch for the bug
  106. 106. Merge it into (‘pu’ and) ‘next’ first. merge reset and merge
  107. 107. Then merge it into ‘master’ if it looks good. merge
  108. 108. Note that you can merge the fix branch into ‘master’ directly when the commits in fix branch are trivial. fix-branch for the bug
  109. 109. Note that you can merge the fix branch into ‘master’ directly when the commits in fix branch are trivial. merge
  110. 110. But after that, don’t forget to merge ‘master’ into ‘next’ for the fix will be included in ‘next’ (‘next’ must have the bug because it has all topics merged into ‘master’) merge reset and merge
  111. 111. There is another situation for fixing bugs. If the release v1.0.0 have a bug, how should we address it? a bug found
  112. 112. Fix it on ‘master’ and let v1.0.0 users upgrade to ‘master’? But some v1.0.0 users don’t want to use new features merged into ‘master’.
  113. 113. So you want a new integration branch only for bug fixing. ‘maint’ is such a branch. It will be branched from the latest feature release, i.e. v1.0.0. maint create branch
  114. 114. The fix branch have to be branched from ‘maint’. Don’t branch from ‘master’ or any upstream. fix-branch for the bug
  115. 115. If you branch the fix branch for ‘maint’ from ‘master’... *WRONG* fix-branch for the bug *WRONG*
  116. 116. When the fix branch merged into ‘maint’, additional topics are also merged into ‘maint’. Those downwards merging will break ‘maint’ branch. *WRONG* merge *WRONG* unintentionally merged commits
  117. 117. You can handle this case by cherry-pick the commit into ‘maint’, but you should take care where you fork off from. cherry-pick workaround
  118. 118. So the fix branch should be forked off from ‘maint’. As a general rule, fork off topics from the oldest integration branch which the topics will be finally merged into. fix-branch for the bug
  119. 119. Basically merge the fix branch for ‘maint’ into ‘next’ (or ‘pu’) first as usual because ‘maint’ never get reset. merge reset and merge
  120. 120. Then merge it into ‘maint’ when it looks good on ‘next’. merge
  121. 121. But...
  122. 122. Of course you can merge fix branches directly into ‘maint’ when they are trivial. merge
  123. 123. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits.
  124. 124. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits. merge
  125. 125. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits.
  126. 126. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits. merge
  127. 127. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits. merge
  128. 128. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits. merge
  129. 129. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits. reset and merge
  130. 130. Sometimes you should merge ‘maint’ into ‘master’, and merge ‘master’ into ‘next’ for propagation of the fixes. Periodic upward merges are good habits.
  131. 131. When some fixes accumulated in ‘maint’, publish a fix- release.
  132. 132. Tag v1.0.1 on ‘maint’ for the fix-release and push it. v1. 0.1 tag
  133. 133. Well, after a while you want to make a new feature-release. And you want have a code-freeze period for this release.
  134. 134. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. merge fix branches only while frozen
  135. 135. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix fix feature
  136. 136. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature fix
  137. 137. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature merging maint is ok fix
  138. 138. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature merging fix branches are also ok fix
  139. 139. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature Don’t merge feature branches fix
  140. 140. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature Don’t merge feature branches fix
  141. 141. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature fix
  142. 142. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature fix even though good enough for master...
  143. 143. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature Don’t merge ANY feature branches fix
  144. 144. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature Don’t merge ANY feature branches fix
  145. 145. To freeze your code, just stop merging feature topics and only merge fix-topics, including ‘maint’, into ‘master’. fix feature fix
  146. 146. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. merging feature branches are OKay fix feature fix
  147. 147. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. merging fix branches are also OKay fix feature fix
  148. 148. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze.
  149. 149. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. rebase rebasing active topics are OKay
  150. 150. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. rebase rebasing active topics are OKay
  151. 151. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. reverting or dropping active branches are also OKay revert
  152. 152. You can merge feature topics into ‘next’ for integration of them while ‘master’ is frozen. So you don’t have to stop developing for the code-freeze. reverting or dropping active branches are also OKay
  153. 153. The code-freeze period has done. Now you will make feature-release.
  154. 154. Before tagging, make sure ‘maint’ is fully merged into ‘master’ by git merge maint on ‘master’. If not merged, some fixes will be missing from the new release. Already fully merged into master in this case
  155. 155. Now release it. Tag v1.1.0 on ‘master’ for the feature- release and push it. tag v1. 1.0
  156. 156. New release has done. But you have some tasks for the ‘next’ and ‘maint’ after feature-release
  157. 157. Let’s do for ‘next’. At first reset ‘next’ to ‘master’ reset to master leave a tag for in case messed up
  158. 158. Then merge active topics they weren’t included in the last release. (And rebuild ‘pu’ if needed) merge active branches
  159. 159. Then merge active topics they weren’t included in the last release. (And rebuild ‘pu’ if needed) merge active branches
  160. 160. Then merge active topics they weren’t included in the last release. (And rebuild ‘pu’ if needed) check diff for making sure that they are equivalentdiff
  161. 161. Then merge active topics they weren’t included in the last release. (And rebuild ‘pu’ if needed) rebuild pu
  162. 162. This rewind and reconstruction of ‘next’ is for cleaning up the history of it. Actually you can do this anytime with an announcement. But it is good point to do this right after a feature release.
  163. 163. This rewind and reconstruction of ‘next’ is for cleaning up the history of it. Actually you can do this anytime with an announcement. But it is good point to do this right after a feature release.
  164. 164. Next, let’s see about ‘maint’ The task for ‘maint’ is simple. Just fast-forward ‘maint’ to ‘master’. Fast-Foward to master
  165. 165. This is done by git merge --ff-only master on ‘maint’. If it fail, the last release is missing some fixes because ‘maint’ must have some commits that are not in ‘master’. Fast-Foward to master
  166. 166. If you merge ‘maint’ into ‘master’ before the release like already shown, the fast-forward will succeed.
  167. 167. Note that if you want keep maintenance branch for the previous feature-release, you can leave another maint branch, e.g. maint-1.0, for it. maint-1.0
  168. 168. After the feature-release, repeat the same workflows already shown. This is the gitworkflows(7). Keep on developing with it. New topic and...
  169. 169. Conclusion (1/2) ● Use throw-away integration branch like pu ● Merge topics into the throw-away(TA) first ● Test in TAs before merging topics into master ● You can use hybrid of TA and non-TA like next ● next can be reset with announcements. ● master and maint cannot be reset
  170. 170. Conclusion (2/2) ● Don’t base your work on pu or next ● Fork off topics from the oldest integ-branch which the topics will be finally merged into ● Merge integration branches upwards ● Tag master for feature-releases ● Tag maint for fix-releases
  171. 171. See also ● gitworkflows(7) ● Documentation/SubmittingPatches in Git source tree ● MaintNote in ‘todo’ branch of git.git ● the Git Blame blog by Junio C Hamano
  172. 172. Q and A
  173. 173. Q: What is the difference between next and pu? A: It depends. gitworkflows(7) saids pu, throw-away, is for testing the interaction of topics but according to the recent MaintNotes in the git.git, pu is a sort of reminder for the maintainer. next is said to be for testing/polishing for master in both documents. IMHO pu is a working space and next is a staging area for master. It looks like working tree and index of Git itself.
  174. 174. Q: Do I have to keep {‘pu’, ‘next’, ‘maint’} A: No, you don’t. Just create and keep them if you need. But I recommend you to use a throw-away at least. You may keep it in your local repos only (i.e. make sure tests are succeeded and then push master). I’ve seen a project that have only ‘master’, ‘pu’ and another project that have ‘master’, ‘master-pu’, ‘maint’, ‘maint-pu’.
  175. 175. Q: Do I have to keep so many topics? A: Yes. You have to keep them until they’ve been merged into ‘master’ or ‘maint’ But you can assign someone you trust to maintain a certain subsystem with gitworkflows. Then you can just merge his/her ‘master’ into your ‘master’. (actually you need a throw-away) This is the reason why gitworkflows is thought to be scalable.
  176. 176. Q: Do I have to merge a single branch repeatedly? A: Yes. When you become tired of resolving identical conflicts, enable git-rerere(1). The ‘rerere’ stands for Reuse Recorded Resolution. It will help you to resolve conflicts that have been resolved once before.
  177. 177. Q: May I use GitHub pull requests with gitworkflows? A: Yes, of course. For the git.git, GitHub pull requests are simply ignored but it’s just a policy of the project. “Merge Workflow” in the online manual gitworkflows(7) will suit for GitHub users.
  178. 178. Thank you
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×