Dancer::Development::Integration - guide for Dancer's core-team members
This documentation describes the procedure used for integrators to review and
merge contributions sent via pull-requests.
Every core-team member should read and apply the procedures described here. This
will allow for a better history and more consistency in our ways of handling
the (increasing number!) of pull requests.
We will first define the most important terms used in this documentation:
Acronym for Pull Request
A GitHub user who had forked and cloned the official Dancer's repo, and who
has sent a PR.
- Integration branch
This branch is the branch used to merge all contributions. This is a
git-flow convention. In Dancer, our integration branch is
As explained in Dancer::Development, every PR should be based on the
integration branch. If not, this is enough to refuse the PR (it makes the
life of the integrator much harder if this is not the case).
A member of Dancer's core-team who is responsible for reviewing and either
rejecting the PR, or merging it into the integration branch.
This procedure describes how an integrator should process a PR.
Let's say the user $user
has sent a PR, he has followed the
instructions described in Dancer::Development so his work is based on the
integration branch ("devel").
All the procedure described here is designed to avoid unnecessary
recursive-merge, in order to keep a clean and flat history in the integration
Of course, we could just pull from $user
"devel" branch, but this would shift the history because of
recursive merge, most of the time.
To avoid that, we're going to pull the commits of $user
into a temporary branch, and then cherry-pick the commits we want.
In order to have a clean history, like the one we got with git-flow when working
on a feature, we're going to do that in a topic branch, named
"review/$user". Then, this branch will be merged into
"devel" and we will just have to drop it.
First, we make sure we are in sync with "origin/devel"
git checkout devel
git pull origin devel
Then, from that branch we create a temp
git checkout -b temp
We pull here from $user
git pull <user repo> <pr/branch>
Here, either the pull was run as a fast-forward or as a recursive merge. If we
have a FF, we can forget about the temp
branch and do the pull directly
in "devel". If not, we'll have to cherry-pick the commits by hand.
From devel, we first create the final "review" branch:
git checkout devel
git checkout -b review/$user
Then we cherry-pick all the commits we want. To know them, we just have to go
and inspect the history (with "git log").
When we have the list of commits we want:
for commit in C1 C2 C3 ... CN
git cherry-pick $commit
(Another option is to use "git rebase -i" to manually select the list
of commits to cherry-pick/rebase.)
Then we can review the code, do whatever we want, maybe add some commits to
When we're happy with the change set, we can merge into devel:
git checkout devel
git merge --no-ff review/$user
Note the "--no-ff" switch is used to make sure we'll see a nice commit
named "Merge branch 'review/$user' into devel". This is on purpose
and mimic the behaviour of git-flow.
Your local "devel" branch is now merged, and can be pushed to the
$ git push origin devel
We have one main release cycle. This is the release cycle based on the
branch. We use this branch to build new releases, with new stuff
all the new shiny commits we want.
Those release are built with git-flow (with "git-flow release") and
are then uploaded to CPAN.
Since Dancer 1.2, we also have another parallel release cycle which is what we
call the frozen
branch. It's a maintenance-only release cycle. That
branch is created from the tag of the first release of a stable
(namely a release series with an even minor number).
This branch must be used only for bug-fixing the stable releases. Nothing new
should occur in that branch.
Let's take an example with Dancer 1.2003 and Dancer 1.3002.
- Dancer 1.2003 is the last stable release of Dancer. Its
codebase is handled in the frozen branch, that has been created
from the tag 1.2000.
- Dancer 1.3002 is the last release of Dancer. As it belongs
to a development series, it can provide new features, code refactoring and
deprecations. Its codebase is handled by the integration branch,
- When a bug is found in 1.2xxx, it's fixed in the
"frozen" branch, and a new release is built from here and then
uploaded to CPAN.
- Whenever the team wants to, they can release new versions
of 1.3xxx from the devel branch, using "git-flow release
- When the team finds that the current state of devel
(namely, the last version of 1.3xxx) is stable and mature enough. They can
decide it will be the new stable version.
Then, a release 1.4000_01 is built from devel, an upload is done to CPAN,
and when ready, the 1.40001 can be uploaded the same way.
From that moment, the master branch is merged into frozen in order to be
able to hotfix the frozen branch in the future.
It's now possible for the team to continue working on new stuff in devel,
bumping the version number to 1.5000_01
This documentation has been written by Alexis Sukrieh
Dancer Core Developers
This software is copyright (c) 2010 by Alexis Sukrieh.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.