1Dancer::Development::InUtseegrraCtoinotnr(i3b)uted PerlDDaonccuemre:n:tDaetvieolnopment::Integration(3)
2
3
4

NAME

6       Dancer::Development::Integration - guide for Dancer's core-team members
7

VERSION

9       version 1.3513
10

DESCRIPTION

12       This documentation describes the procedure used for integrators to
13       review and merge contributions sent via pull-requests.
14
15       Every core-team member should read and apply the procedures described
16       here. This will allow for a better history and more consistency in our
17       ways of handling the (increasing number!) of pull requests.
18

TERMS

20       We will first define the most important terms used in this
21       documentation:
22
23PR
24
25           Acronym for Pull Request
26
27       •   Contributor
28
29           A GitHub user who had forked and cloned the official Dancer's repo,
30           and who has sent a PR.
31
32       •   Integration branch
33
34           This branch is the branch used to merge all contributions. This is
35           a git-flow convention. In Dancer, our integration branch is
36           "devel".
37
38           As explained in Dancer::Development, every PR should be based on
39           the integration branch. If not, this is enough to refuse the PR (it
40           makes the life of the integrator much harder if this is not the
41           case).
42
43       •   Integrator
44
45           A member of Dancer's core-team who is responsible for reviewing and
46           either rejecting the PR, or merging it into the integration branch.
47

PROCEDURES

49   Processing a Pull Request
50       This procedure describes how an integrator should process a PR.
51
52       Let's say the user $user has sent a PR, he has followed the
53       instructions described in Dancer::Development so his work is based on
54       the integration branch ("devel").
55
56       All the procedure described here is designed to avoid unnecessary
57       recursive-merge, in order to keep a clean and flat history in the
58       integration branch.
59
60       Of course, we could just pull from $user into our "devel" branch, but
61       this would shift the history because of recursive merge, most of the
62       time.
63
64       To avoid that, we're going to pull the commits of $user into a
65       temporary branch, and then cherry-pick the commits we want.
66
67       In order to have a clean history, like the one we got with git-flow
68       when working on a feature, we're going to do that in a topic branch,
69       named "review/$user". Then, this branch will be merged into "devel" and
70       we will just have to drop it.
71
72       First, we make sure we are in sync with "origin/devel"
73
74           git checkout devel
75           git pull origin devel
76
77       Then, from that branch we create a temp sandbox
78
79           git checkout -b temp
80
81       We pull here from $user
82
83           git pull <user repo> <pr/branch>
84
85       Here, either the pull was run as a fast-forward or as a recursive
86       merge. If we have a FF, we can forget about the temp branch and do the
87       pull directly in "devel". If not, we'll have to cherry-pick the commits
88       by hand.
89
90       From devel, we first create the final "review" branch:
91
92           git checkout devel
93           git checkout -b review/$user
94
95       Then we cherry-pick all the commits we want. To know them, we just have
96       to go into temp and inspect the history (with "git log").
97
98       When we have the list of commits we want:
99
100           for commit in C1 C2 C3 ... CN
101           do
102               git cherry-pick $commit
103           done
104
105       (Another option is to use "git rebase -i" to manually select the list
106       of commits to cherry-pick/rebase.)
107
108       Then we can review the code, do whatever we want, maybe add some
109       commits to change something.
110
111       When we're happy with the change set, we can merge into devel:
112
113           git checkout devel
114           git merge --no-ff review/$user
115
116       Note the "--no-ff" switch is used to make sure we'll see a nice commit
117       named "Merge branch 'review/$user' into devel". This is on purpose and
118       mimic the behaviour of git-flow.
119
120       Your local "devel" branch is now merged, and can be pushed to the
121       remote.
122
123           $ git push origin devel
124

RELEASE CYCLES

126       We have one main release cycle. This is the release cycle based on the
127       devel branch. We use this branch to build new releases, with new stuff
128       all the new shiny commits we want.
129
130       Those release are built with git-flow (with "git-flow release") and are
131       then uploaded to CPAN.
132
133       Since Dancer 1.2, we also have another parallel release cycle which is
134       what we call the frozen branch. It's a maintenance-only release cycle.
135       That branch is created from the tag of the first release of a stable
136       version (namely a release series with an even minor number).
137
138       This branch must be used only for bug-fixing the stable releases.
139       Nothing new should occur in that branch.
140
141       Let's take an example with Dancer 1.2003 and Dancer 1.3002.
142
143       •   Dancer 1.2003 is the last stable release of Dancer. Its codebase is
144           handled in the frozen branch, that has been created from the tag
145           1.2000.
146
147       •   Dancer 1.3002 is the last release of Dancer. As it belongs to a
148           development series, it can provide new features, code refactoring
149           and deprecations. Its codebase is handled by the integration
150           branch, "devel".
151
152       •   When a bug is found in 1.2xxx, it's fixed in the "frozen" branch,
153           and a new release is built from here and then uploaded to CPAN.
154
155       •   Whenever the team wants to, they can release new versions of 1.3xxx
156           from the devel branch, using "git-flow release start".
157
158       •   When the team finds that the current state of devel (namely, the
159           last version of 1.3xxx) is stable and mature enough. They can
160           decide it will be the new stable version.
161
162           Then, a release 1.4000_01 is built from devel, an upload is done to
163           CPAN, and when ready, the 1.40001 can be uploaded the same way.
164
165           From that moment, the master branch is merged into frozen in order
166           to be able to hotfix the frozen branch in the future.
167
168           It's now possible for the team to continue working on new stuff in
169           devel, bumping the version number to 1.5000_01
170

AUTHOR

172       This documentation has been written by Alexis Sukrieh
173       "<sukria@sukria.net>".
174

AUTHOR

176       Dancer Core Developers
177
179       This software is copyright (c) 2010 by Alexis Sukrieh.
180
181       This is free software; you can redistribute it and/or modify it under
182       the same terms as the Perl 5 programming language system itself.
183
184
185
186perl v5.36.0                      2022-07-22Dancer::Development::Integration(3)
Impressum