Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit b020801

Browse files
Add description in README
1 parent 94a23af commit b020801

File tree

4 files changed

+104
-9
lines changed

4 files changed

+104
-9
lines changed

‎.editorconfig‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ charset = utf-8
77
end_of_line = lf
88
insert_final_newline = true
99
trim_trailing_whitespace = true
10-
max_line_length = 80
10+
max_line_length = 120

‎README.adoc‎

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
= Gitworkflow
2+
:homepage: https://github.com/rocketraman/gitworkflows
23

34
The https://git.kernel.org/pub/scm/git/git.git/[git.git] project, responsible for the creation and maintenance of the
4-
https://git-scm.com/[git] tool itself, uses an amazing workflow I call "gitworkflow", in deference to its creators
5+
https://git-scm.com/[git] tool itself, uses a powerful workflow I call "gitworkflow", in deference to its creators
56
and the https://git-scm.com/docs/gitworkflows[man page] in which it is described.
67

78
I describe the advantages of this workflow, in comparison to the popular
@@ -10,3 +11,100 @@ http://endoflineblog.com/oneflow-a-git-branching-model-and-workflow[OneFlow] in
1011
https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[How the Creators of Git do Branching].
1112

1213
This repository is meant to be a place in which tools and documentation related to gitworkflow can be created.
14+
15+
== TL;DR
16+
17+
* See the link:./docs/concepts-summary.adoc[Concepts Summary]
18+
* See the link:./docs/task-oriented-primer.adoc[Task-Oriented Primer]
19+
20+
== Key Advantages
21+
22+
The key advantages gitworkflow over GitFlow and OneFlow all come from treating topics as first-class citizens, not just
23+
temporary placeholders for unfinished code.
24+
25+
=== Amazing History
26+
27+
Gitworkflow presents a history that code historians, and conscientious developers can love. It can easily present both
28+
summary (e.g. "show me all the topics merged into a release") and highly detailed views (e.g. "show me all the commits
29+
related to a topic").
30+
31+
=== Continuous Integration, Done Right
32+
33+
Ever struggled with the decision about when to merge a topic branch to the main branch (`develop` in GitFlow / `master`
34+
everywhere else)?
35+
36+
With GitFlow and OneFlow, in order to get the benefit of
37+
https://martinfowler.com/articles/continuousIntegration.html[Continuous Integration], you have to either test each topic
38+
branch in isolation, OR you have to merge it to the main line. Testing the topic in isolation, well, tests in isolation,
39+
which is "continuous", but isn't "integration". Waiting to merge until the topic is "done" means you can only test it
40+
along with other work that is also "done". This is "integration", but it isn't "continuous". So neither approach gets
41+
us continuous integration.
42+
43+
This tension exists between "continuous" and "integration" because in most non-trivial projects, topics don't have a
44+
binary done/not done state: they are almost always a work in progress, with their stability being an analog continuum,
45+
not a digital value. We really want to do "continuous integration" of topics, even before they are considered "done"
46+
(i.e. released).
47+
48+
With gitworkflow, the stability level of a topic is explicit -- and we can do true "continuous integration" of all the
49+
unreleased alpha-quality topics merged together to create an "alpha" release, all the unreleased beta-quality topics
50+
merged to create a "beta" release, and lastly all of the released topics.
51+
52+
The early "continuous integration" of topics before they are "done" allows identification of conflicting work on
53+
different topics early in their development, prompting the right conversations and coordination between devs at the
54+
right time.
55+
56+
==== Make Your Topics Great
57+
58+
Gitworkflow allows the alpha and beta-quality integration branches to be rewound and rebuild. This property allows
59+
topics to be massaged via interactive rebase until they form a series of easily understandable and reviewable chunks of
60+
work. With other flows, this is only an option until the topic is considered "done" and is merged to the main line for
61+
CI and user testing. Gitworkflow removes the limitation that a topic branch cannot be interactively rebased after it has
62+
been merged for CI and user testing, and generally for alpha-quality topics, this would be expected rather than frowned
63+
on.
64+
65+
=== Flexibility
66+
67+
Sometimes features take longer to develop than expected. Sometimes they don't work well with other work in progress and
68+
need to be thrown away and a new approach taken. Sometimes everyone thinks they are "done", but they don't test well or
69+
they cause regressions.
70+
71+
In most flows, this code is already on the main line of development. It has to be reverted (which can be easy or hard
72+
depending on the flow and the method used to merge the topic).
73+
74+
In contrast, Gitworkflow defines a range of stability levels that the code "graduates" through, from raw unfinished code
75+
("alpha") to code ready for testing ("beta") to code ready for release. Code can spend as much time as it needs to at
76+
each of these "levels", and when code is merged to the main line, it is production-ready. Thus gitworkflow supports
77+
continuous deployment scenarios as well.
78+
79+
Gitworkflow allows you to define your own stability levels if you wish: add or remove integration branches as necessary.
80+
81+
== Main Insights
82+
83+
One key insight that makes gitworkflow work over flows like GitFlow and OneFlow is that: git is smarter than your
84+
average source control system. Topics don't have to be merged _only into the branch they were started from_, which seems
85+
to be the implicit or explicit assumption most flow authors make. In git, the topic can be merged _into any branch that
86+
it shares a common ancestor with_.
87+
88+
This means that topic branches can be merged to multiple integration branches, each with a different purpose
89+
corresponding to the stability levels defined above.
90+
91+
A second key insight is that, when topics are first-class citizens, early integration branches are just ephemeral
92+
placeholders for various combinations of topics, and can easily be recreated (rewind and rebuild). The integration
93+
branches are therefore unimportant and don't need to be a limiting factor for work on topics, such as rebasing, and
94+
we are free to experiment with moving topics in and out of them.
95+
96+
== Disadvantages
97+
98+
Gitworkfow is more complicated, and harder to understand than most (probably all) other flows. It requires more
99+
understanding of git concepts and capabilities. It offers significant powerful capabilities to complex multi-dimensional
100+
products with a team of developers, but does have more "overhead" in the sense of multiple things to track and
101+
understand. This means that:
102+
103+
* Gitworkflow should not be used without significant team maturity using, or willingness to learn, git, and
104+
* Gitworkflow is serious overkill for trivial or one-man projects (but these might be a good place to try it out).
105+
106+
== Interested in Learning More?
107+
108+
* Read the https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb[blog post]
109+
* See the link:./docs/concepts-summary.adoc[Concepts Summary]
110+
* See the link:./docs/task-oriented-primer.adoc[Task-Oriented Primer]

‎docs/concepts-summary.adoc‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -75,11 +75,11 @@ and it has the following properties:
7575
issues
7676
* usually deployed to a testing environment
7777
at the beginning of every development cycle, rewound to `master`, but otherwise never rewound
78-
* contains all of `master` i.e. always based on the head of `master`
78+
* usually contains all of `master` i.e. usually based on the head of `master`
7979
* when a release is made, if a topic branch currently in `next` is not stable enough promotion to `master`, it is
8080
simply not merged to `master` -- instead, it is merged to the next iteration of `next`
81-
* may be rewound to `master` at any time -- but usually after a release
82-
* it is *never* merged into another branch
81+
* may be rewound to `master` at any time, and rebuilt with topics still in `next` -- but usually after a release
82+
* it is *never* merged into any another branch
8383
* new topics are not usually based on `next`
8484
** one exception: if a topic is not expected to be stable for the next release, and the creator understands that
8585
the branch will need to be rebased when `next` is rewound and rebuilt, this is ok and may result in fewer conflicts
@@ -96,7 +96,7 @@ and it has the following properties:
9696
* to test / provide early warning whether the unmerged topic branches integrate cleanly -- if not, some communication
9797
to coordinate changes on topics is necessary
9898
* may be rewound to `master` at any time -- but usually once every day or every second day
99-
* it is *never* merged into another branch
99+
* it is *never* merged into any another branch
100100
* new topics are not usually based on `pu`
101101

102102
==== maint (and maint-X.Y)

‎docs/task-oriented-primer.adoc‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -283,9 +283,6 @@ Brush up on these commands and concepts:
283283
* git https://git-scm.com/blog/2010/03/08/rerere.html[rerere]
284284
* See also alias git mb ("merge branch") when working with remote branches
285285

286-
The commands above may be used to semi-automate this process so that it can be run often -- once a day, or even as
287-
needed.
288-
289286
===== Tools
290287

291288
TODO: Link to script to rebuild `pu` based on topics currently in `pu`

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /