-
Notifications
You must be signed in to change notification settings - Fork 0
Home
To clone a sequip repository for the first time, and get it set up:
$ git clone https://github.com/nawrocke/sequip.git
You're set up on the stable master branch. To do any development, you need to work on the develop
branch, generally by creating and merging feature branches.
To switch to develop branches:
$ cd sequip
$ git checkout develop
For information about our git workflow, read on.
sequip uses the popular git workflow that's often just called
"git flow". Go read the 2010 blog post by Vincent
Driessen
that describes it. But we use it with the difference that
we don't mind having feature branches on origin
.
In what follows, first we'll give concise-ish examples of the flow for normal development, making a release, and making a "hotfix". A summary of the principles and rationale follows the examples.
Generally, for any changes you make to our code, you will make on a
feature branch, off of develop
. So first you create your branch:
$ git checkout -b myfeature develop
Now you work, for however long it takes. You can make commits on your
myfeature
branch locally, and/or you can push your branch up to the
origin and commit there too, as you see fit.
When you're done, and you've tested your new feature, you merge it to
develop
(using --no-ff
, which makes sure a clean new commit object
gets created), and delete your feature branch:
$ git checkout develop
$ git merge --no-ff -m "Merges myfeature branch to develop" myfeature
$ git branch -d myfeature
$ git push origin --delete myfeature
$ git push origin develop
Alternatively, if you're sure your change is going to be a single
commit, you can work directly on the develop
branch.
$ git checkout develop
# make your changes
$ git commit
$ git push origin develop
If your work on a feature is taking a long time (days, weeks...), and
if the develop
trunk is accumulating changes you want, you might
want to periodically merge them in:
$ git checkout myfeature
$ git merge --no-ff -m "Merges develop branch into myfeature" develop
To make a release, you're going to make a release branch of the
code. You assign an appropriate version number, test and
stabilize. When everything is ready, you merge to master
and tag
that commit with the version number; then you also merge back to
develop
, and delete the release branch.
For example, here's the git flow for a sequip release.
Suppose sequip is currently at version 0.03 and suppose we decide
this release will be sequip 0.1, We can make a new release from
sequip's develop
branch:
$ cd sequip
$ git checkout develop # only necessary if you're not already on develop
$ git checkout -b release-0.1 develop
# change version number to 0.1 at one place at top of each README and
# each .pm file. Update date in README.
$ git commit -a -m "Version number bumped to 0.1"
# do and commit any other work needed to test/stabilize the release.
When you're finished merge the sequip release branch as follows:
$ git checkout master
$ git merge --no-ff -m "Merges release-0.1 branch into master" release-0.1
$ git tag -a -m "Tags sequip 0.1 release" sequip-0.1
$ git push origin sequip-0.1
# Now merge release branch back to develop...
$ git checkout develop
$ git merge --no-ff -m "Merges release-0.1 branch into develop" release-0.1
$ git push
$ git branch -d release-0.1
$ git push origin --delete release-0.1
If you need to fix a critical bug and make a new release immediately,
you create a hotfix
release with an updated version number, and the
hotfix release is named accordingly: for example, if we screwed up
sequip, hotfix-0.04
is the updated 0.04 release.
A hotfix branch comes off master
, but otherwise is much like a
release branch.
$ cd sequip
$ git checkout -b hotfix-0.04 master
# change version number to 0.04 at one place at top of each README and
# sequip.pm. Update date in README.
$ git commit -a -m "Version number bumped to 0.04"
Now you fix the bug(s), in one or more commits. When you're done, the finishing procedure is just like a release:
$ git checkout master
$ git merge --no-ff hotfix-0.04
$ git push
$ git tag -a -m "Tags sequip 0.04 release" sequip-0.04
$ git push origin sequip-0.04
$ git checkout develop
$ git merge --no-ff hotfix-0.04
$ git push
$ git branch -d hotfix-0.04
There are two long-lived sequip branches: origin/master
, and origin/develop
. All other branches
have limited lifetimes.
master
is stable. Every commit object on master
is a tagged
release, and vice versa.
develop
is for ongoing development destined to be in the next
release. develop
should be in a close-to-release state. Another
package (e.g. VADR) may need to create a release of a downstream
dependency (e.g. sequip) at short notice. Therefore, commit objects on
develop
are either small features in a single commit, or a merge of
a finished feature branch.
We make a feature branch off develop
for any nontrivial new work --
anything that you aren't sure will be a single commit on develop
. A
feature branch:
- comes from
develop
- is named anything informative (except
master
,develop
,hotfix-*
orrelease-*
) - is merged back to
develop
(and deleted) when you're done - is deleted once merged
We make a release branch off develop
when we're making a release.
A release branch:
- comes from
develop
- is named
release-<version>
, such asrelease-1.2
- first commit on the hotfix branch consists of bumping version/date
- is merged to
master
when you're done, and that new commit gets tagged as a release - is then merged back to
develop
too - is deleted once merged
We make a hotfix branch off master
for a critical immediate fix to
the current release. A hotfix branch:
- comes from
master
- is named
hotfix-<version>
, such ashotfix-1.2.1
- first commit on the hotfix branch consists of bumping version/date/copyright
- is merged back to
master
when you're done, and that new commit object gets tagged as a release. - is then merged back to
develop
too - is deleted once merged