.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Dancer::Development::Integration 3pm" .TH Dancer::Development::Integration 3pm "2015-11-07" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dancer::Development::Integration \- guide for Dancer's core\-team members .SH "VERSION" .IX Header "VERSION" version 1.3202 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This documentation describes the procedure used for integrators to review and merge contributions sent via pull-requests. .PP 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. .SH "TERMS" .IX Header "TERMS" We will first define the most important terms used in this documentation: .IP "\(bu" 4 \&\fB\s-1PR\s0\fR .Sp Acronym for \fBP\fRull \fBR\fRequest .IP "\(bu" 4 Contributor .Sp A GitHub user who had forked and cloned the official Dancer's repo, and who has sent a \s-1PR.\s0 .IP "\(bu" 4 Integration branch .Sp This branch is the branch used to merge all contributions. This is a git-flow convention. In Dancer, our integration branch is \f(CW\*(C`devel\*(C'\fR. .Sp As explained in Dancer::Development, every \s-1PR\s0 should be based on the integration branch. If not, this is enough to refuse the \s-1PR \s0(it makes the life of the integrator much harder if this is not the case). .IP "\(bu" 4 Integrator .Sp A member of Dancer's core-team who is responsible for reviewing and either rejecting the \s-1PR,\s0 or merging it into the integration branch. .SH "PROCEDURES" .IX Header "PROCEDURES" .SS "Processing a Pull Request" .IX Subsection "Processing a Pull Request" This procedure describes how an integrator should process a \s-1PR. \s0 .PP Let's say the user \fI\f(CI$user\fI\fR has sent a \s-1PR,\s0 he has followed the instructions described in Dancer::Development so his work is based on the integration branch (\f(CW\*(C`devel\*(C'\fR). .PP All the procedure described here is designed to avoid unnecessary recursive-merge, in order to keep a clean and flat history in the integration branch. .PP Of course, we could just pull from \fI\f(CI$user\fI\fR into our \f(CW\*(C`devel\*(C'\fR branch, but this would shift the history because of recursive merge, most of the time. .PP To avoid that, we're going to pull the commits of \fI\f(CI$user\fI\fR into a temporary branch, and then cherry-pick the commits we want. .PP 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 \f(CW\*(C`review/$user\*(C'\fR. Then, this branch will be merged into \f(CW\*(C`devel\*(C'\fR and we will just have to drop it. .PP First, we make sure we are in sync with \f(CW\*(C`origin/devel\*(C'\fR .PP .Vb 2 \& git checkout devel \& git pull origin devel .Ve .PP Then, from that branch we create a \fItemp\fR sandbox .PP .Vb 1 \& git checkout \-b temp .Ve .PP We pull here from \fI\f(CI$user\fI\fR .PP .Vb 1 \& git pull .Ve .PP Here, either the pull was run as a fast-forward or as a recursive merge. If we have a \s-1FF,\s0 we can forget about the \fItemp\fR branch and do the pull directly in \f(CW\*(C`devel\*(C'\fR. If not, we'll have to cherry-pick the commits by hand. .PP From devel, we first create the final \f(CW\*(C`review\*(C'\fR branch: .PP .Vb 2 \& git checkout devel \& git checkout \-b review/$user .Ve .PP Then we cherry-pick all the commits we want. To know them, we just have to go into \fItemp\fR and inspect the history (with \f(CW\*(C`git log\*(C'\fR). .PP When we have the list of commits we want: .PP .Vb 4 \& for commit in C1 C2 C3 ... CN \& do \& git cherry\-pick $commit \& done .Ve .PP (Another option is to use \f(CW\*(C`git rebase \-i\*(C'\fR to manually select the list of commits to cherry\-pick/rebase.) .PP Then we can review the code, do whatever we want, maybe add some commits to change something. .PP When we're happy with the change set, we can merge into devel: .PP .Vb 2 \& git checkout devel \& git merge \-\-no\-ff review/$user .Ve .PP Note the \f(CW\*(C`\-\-no\-ff\*(C'\fR switch is used to make sure we'll see a nice commit named \f(CW\*(C`Merge branch \*(Aqreview/$user\*(Aq into devel\*(C'\fR. This is on purpose and mimic the behaviour of git-flow. .PP Your local \f(CW\*(C`devel\*(C'\fR branch is now merged, and can be pushed to the remote. .PP .Vb 1 \& $ git push origin devel .Ve .SH "RELEASE CYCLES" .IX Header "RELEASE CYCLES" We have one main release cycle. This is the release cycle based on the \fIdevel\fR branch. We use this branch to build new releases, with new stuff all the new shiny commits we want. .PP Those release are built with git-flow (with \f(CW\*(C`git\-flow release\*(C'\fR) and are then uploaded to \s-1CPAN.\s0 .PP Since Dancer 1.2, we also have another parallel release cycle which is what we call the \fIfrozen\fR branch. It's a maintenance-only release cycle. That branch is created from the tag of the first release of a \fIstable\fR version (namely a release series with an even minor number). .PP This branch must be used only for bug-fixing the stable releases. Nothing new should occur in that branch. .PP Let's take an example with Dancer 1.2003 and Dancer 1.3002. .IP "\(bu" 4 Dancer 1.2003 is the last stable release of Dancer. Its codebase is handled in the \fIfrozen\fR branch, that has been created from the tag \f(CW1.2000\fR. .IP "\(bu" 4 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, \f(CW\*(C`devel\*(C'\fR. .IP "\(bu" 4 When a bug is found in 1.2xxx, it's fixed in the \f(CW\*(C`frozen\*(C'\fR branch, and a new release is built from here and then uploaded to \s-1CPAN.\s0 .IP "\(bu" 4 Whenever the team wants to, they can release new versions of 1.3xxx from the devel branch, using \f(CW\*(C`git\-flow release start\*(C'\fR. .IP "\(bu" 4 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. .Sp Then, a release 1.4000_01 is built from devel, an upload is done to \s-1CPAN,\s0 and when ready, the 1.40001 can be uploaded the same way. .Sp From that moment, the master branch is merged into frozen in order to be able to hotfix the frozen branch in the future. .Sp It's now possible for the team to continue working on new stuff in devel, bumping the version number to 1.5000_01 .SH "AUTHOR" .IX Header "AUTHOR" This documentation has been written by Alexis Sukrieh \f(CW\*(C`\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Dancer Core Developers .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by Alexis Sukrieh. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.