An earlier article described Gitworkflow. This document goes into more details, focusing on a task-oriented visual presentation to make using gitworkflow as simple as possible.
See Concepts Summary
All of the below summaries given using the git command line. Learn it!
Topics are usually created by branching from master. Sometimes, from maint.
Question: Is this topic eventually going to be merged to the existing release?
-
If yes, then branch from
master -
If no, then branch from
maint
|
Warning
|
Never commit directly to next or pu without a topic branch — these changes will be lost.
|
Brush up on these commands and concepts:
Create a new topic branch from master (see the Concepts Summary for a good naming
convention):
(master) $ git checkout -b topic-branch
Switched to a new branch 'topic-branch'
(topic-branch) $
Now develop your topic, committing as you go. Write good commit messages. Use git rebase to make an easily reviewable series of commits.
Once your branch is ready for a review (or simply to back it up), push it to the server:
(topic-branch) $ git push --set-upstream origin topic-branch
You can continue to work on this branch, and use git push to make your changes visible for code review.
If you have long-running development of a feature, you will probably fall behind the master branch. If your branch has
not been merged to another branch (e.g., next) yet, you can rebase/replay your changes on top of the latest master
using
(topic-branch) $ git rebase master
You can continue to interactively rebase a topic to make an easily reviewable series of commits until your branch has
been merged to next. After that, generally only push new commits to your branch (you can still rebase new commits
locally before pushing to the remote).
(topic-branch) $ git rebase -i master
Result of branching from master and committing twice:
Oh oh, you need to develop some work that depends on another topic that has not yet been merged to master. Do not
base your work on next. Instead, create your topic and merge the other topic into it. This explicitly records the
dependency relationship between the topics, and puts the commit resolutions (if any) on the right branch.
Brush up on these commands and concepts:
-
git merge --no-ff
The following tasks are useful to understand for everyone, but especially people who take on the role of release managers (releasing to testing and prod environments).
A topic is stabilized by first merging into pu (or "proposed updates"). The topic may be very raw and will probably
cause regressions or have other problems in its current state. Merging to pu provides opportunity for early feedback
on these problems, and also identifies topics that are conflicting so that the relevant devs can communicate and
determine a strategy.
Brush up on these commands and concepts:
Topics merged to pu can still be interactively rebased. Therefore pu can always be rewound to master (or to just
before the rebased topic was merged), and everything from that point forward merged again ("rewind and rebuild").
Alternatively, the existing topic merge(s) can be reverted, and then the rebased topic merged again.
|
Note
|
When pushing pu back to the server, if there is a conflict because someone else pushed a change to pu at
the same time, do not do a merge pull. Instead, fetch pu, reset-hard to origin/pu, and then merge the topic
branch again. This keeps the history of the integration branch when viewed with --first-parent clean.
|
Result of merging ai/foo-1 and ai/bar-1 into pu:
A topic will generally be merged to next once technical and code reviews are complete, and perhaps some initial
testing via pu has been done. The topic may cause regressions or have other issues that may still need to be solved.
This generally represents all the development that is “done”, but will likely require more stabilization to fix
regressions or other issues based on user testing in a UAT environment.
A topic will spend as much time on next as necessary to stabilize the topic code.
From this point forward, the topic is generally not rebased — only new commits are pushed to it, and merged to next
as necessary. However, this is not a hard-and-fast rule (see Topic Stabilization on Proposed for techniques to deal
with a rebased topic branch previously merged).
See Topic Stabilization on Proposed for the commands and concepts used.
|
Note
|
When pushing next back to the server, if there is a conflict because someone else pushed a change to next at
the same time, do not do a merge pull. Instead, fetch next, reset-hard to origin/next, and then merge the topic
branch again. This keeps the history of the integration branch when viewed with --first-parent clean.
|
We expect to merge a topic to master as soon as that topic is considered stable via testing on next.
Not every commit on master (topic merges) need to form a “release”. In addition, even commits to master that do
form a release are not necessarily deployed to production. The master branch does represent our latest “best” code,
and will generally be run in production environments.
In the following, 0.1 is the current release. Two separate features, developed by Bob, called bob/feature-1 and
bob/feature-2 were initially merged into next. When bob/feature-1 was merged, release 0.2-beta-1 was created.
After bob/feature-2 was merged, release 0.2-beta-2 was created. Lastly, both of these topics graduated, and were
merged to master for release as 0.2.
Verify that maint contains no commits that are also not present in master:
$ git log master..maint
should return nothing. If it returns one or more commits, merge maint into master to preserve any maintenance
changes in future releases.
$ git checkout master
(master) $ git merge maintTag the latest (or a specific) version on master as a “release”.
$ git checkout master
(master) $ git tag -a “v2.7.0” v2.7.0Copy the existing maintenance branch:
$ git checkout `maint`
(maint) $ git branch maint-2.6.4Update the current maintenance branch:
$ git checkout maint
(maint) $ git merge --ff-only master
(maint) $ git push origin maint|
Note
|
If the merge fails because the branch cannot be fast-forwarded, then it is possible some fixes on maint were
missed in the feature release, and are not on master. This will not happen if the content of the branches was
verified as per the earlier instructions.
|
You will likely now wish to Rewind and Rebuild next and Rewind and Rebuild pu.
next may be rewound and rebuilt from master as often as needed. This will normally happen after a release.
Brush up on these commands and concepts:
The commands above may be used to semi-automate this process so that it can be run often — once a day, or even as needed.
A rebuild of pu might be needed if one or more topics have been rebased. This is relatively easy to semi-automate but
some open source tooling would be useful.
pu may be rewound and rebuilt from master as often as needed. This will normally happen after a release.
A rebuild of pu might also be needed if one or more topics have been rebased. This is relatively easy to semi-automate
but some open source tooling would be useful.
|
Tip
|
A CI system may be configured to do this on an hourly or daily basis, automatically rewinding pu and merging in
all pending topics, building, and testing the result. This is a great way to catch conflicts between topics early.
|
Brush up on these commands and concepts: