Commit | Line | Data |
600f7f85 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::Contributing - How to get involved in Moose |
6 | |
7 | =head1 GETTING INVOLVED |
8 | |
04437dba |
9 | Moose is an open project, and we are always willing to accept bug fixes, |
10 | more tests, and documentation patches. Commit bits are given out freely, and |
11 | the L</STANDARD WORKFLOW> is very simple. The general gist is: clone the Git |
12 | repository, create a new topic branch, hack away, then find a committer to |
13 | review your changes. |
600f7f85 |
14 | |
15 | =head1 NEW FEATURES |
16 | |
04437dba |
17 | Moose already has a fairly large feature set, and we are currently |
d85337ff |
18 | B<not> looking to add any major new features to it. If you have an |
19 | idea for a new feature in Moose, you are invited instead to create a |
20 | MooseX module first. |
21 | |
22 | At this stage, no new features will even be considered for addition |
23 | into the core without first being vetted as a MooseX module, unless |
24 | it is absolutely 100% impossible to implement the feature outside the |
25 | core. |
600f7f85 |
26 | |
04437dba |
27 | If you think it is 100% impossible, please come discuss it with us on IRC or |
28 | via e-mail. However, your feature may need a small hook in the core, or a |
29 | refactoring of some core modules, and we are definitely open to that. |
d85337ff |
30 | |
31 | Moose was built from the ground up with the idea of being highly |
32 | extensible, and quite often the feature requests we see can be |
33 | implemented through a couple of small and well placed extensions. Try |
34 | it, it is much easier then you might think. |
600f7f85 |
35 | |
04437dba |
36 | =head1 PEOPLE |
37 | |
38 | As Moose has matured, some structure has emerged in the process. |
39 | |
40 | =over |
41 | |
42 | =item Contributors - people creating a topic or branch |
43 | |
44 | You. |
45 | |
46 | If you have commit access, you can create a topic on the main Moose.git, |
47 | otherwise either give us your SSH key or create your own clone of the |
5af926eb |
48 | L<git://git.moose.perl.org/Moose.git> repository or fork of the GitHub mirror. |
04437dba |
49 | |
50 | =item Core Committers - people reviewing and merging a branch |
51 | |
52 | These people have worked with the Moose codebase for a while. |
53 | |
54 | They've been responsible for large features or branches and can help review |
55 | your changes and apply them to the master branch. |
56 | |
57 | They are also fairly well versed in Git, in order to merge the branches with |
58 | no mistakes (especially when the merge fails), and to provide advice to |
59 | contributors. |
60 | |
61 | =item Cabal - people who can release moose |
62 | |
63 | These people are the ones who have co-maint on Moose itself and can create a |
64 | release. They're listed under L<Moose/CABAL> in the Moose documentation. They |
65 | merge from Master to Stable. |
66 | |
67 | =back |
68 | |
69 | =head1 BRANCH LAYOUT |
70 | |
5af926eb |
71 | The repository is divided into several branches to make maintenance easier for |
04437dba |
72 | everyone involved. The branches below are ordered by level of stability. |
73 | |
74 | =over |
75 | |
76 | =item Stable (refs/heads/stable) |
77 | |
78 | The branch from which releases are cut. When making a new release, the |
79 | release manager merges from master to stable. The stable branch is only |
80 | updated by someone from the Cabal during a release. |
81 | |
82 | =item Master (refs/heads/master) |
83 | |
84 | The branch for new development. This branch is merged into and branched from. |
85 | |
86 | =item Branches (refs/heads/*) |
87 | |
88 | Large community branches for big development "projects". |
89 | |
6106b7a2 |
90 | =item Topics (refs/heads/topic/*) |
04437dba |
91 | |
92 | Small personal branches that have been published for review, but can get |
9840bb38 |
93 | freely rebased. Targeted features that may span a handful of commits. |
04437dba |
94 | |
95 | Any change or bugfix should be created in a topic branch. |
96 | |
97 | =back |
98 | |
99 | =head1 STANDARD WORKFLOW |
100 | |
101 | # update your copy of master |
102 | git checkout master |
103 | git pull --rebase |
104 | |
105 | # create a new topic branch |
106 | git checkout -b topic/my-feature |
107 | |
108 | # hack, commit, feel free to break fast forward |
109 | git commit --amend # allowed |
110 | git rebase --interactive # allowed |
111 | git push --force origin topic/my_feature # allowed |
112 | |
113 | Then go on IRC, ask for someone to review, and merge to master. If it merges |
114 | cleanly and nobody has any objections, then it can be pushed to master. |
115 | |
116 | If it doesn't merge as a fast forward, the author of the branch needs to run |
117 | |
118 | git remote update |
119 | git rebase origin/master # or merge |
120 | |
121 | and bring the branch up to date, so that it can be merged as a fast forward |
122 | into master. |
123 | |
124 | No actual merging (as in a human resolving conflicts) should be done when |
125 | merging into master, only from master into other branches. |
126 | |
127 | =head2 Preparing a topic branch |
128 | |
129 | Before a merge, a topic branch can be cleaned up by the author. |
130 | |
131 | This can be done using interactive rebase to combine commits, etc, or even |
132 | C<git merge --squash> to make the whole topic into a single commit. |
133 | |
134 | Structuring changes like this makes it easier to apply git revert at a later |
135 | date, and encourages a clean and descriptive history that documents what the |
136 | author was trying to do, without the various hangups that happened while they |
137 | were trying to do it (commits like "oops forgot that file" are not only |
138 | unnecessary noise, they also make running things like git bisect or git revert |
139 | harder). |
140 | |
141 | However, by far the biggest benefit is that the number of commits that go into |
142 | master is eventually reduced, and they are simple and coherent, making it much |
143 | easier for people maintaining branches to stay up to date. |
144 | |
145 | All large changes should be documented in L<Moose::Manual::Delta>. |
146 | |
147 | =head1 RELEASE WORKFLOW |
148 | |
149 | git checkout master |
150 | # edit for final version bumping, changelogging, etc |
151 | # prepare release (test suite etc) |
152 | git commit |
153 | git checkout stable |
154 | git merge master # must be a fast forward |
155 | git push both |
156 | # ship & tag |
157 | |
158 | Development releases are made without merging into the stable branch. |
159 | |
160 | =head1 EMERGENCY BUG WORKFLOW (for immediate release) |
161 | |
162 | Anyone can create the necessary fix by branching off of the stable branch: |
163 | |
164 | git remote update |
fd9e0bac |
165 | git checkout -b topic/my-emergency-fix origin/stable |
04437dba |
166 | # hack |
167 | git commit |
168 | |
169 | Then a cabal member merges into stable: |
170 | |
171 | git checkout stable |
172 | git merge topic/my-emergency-fix |
173 | git push |
174 | # release |
175 | git checkout master |
176 | git merge stable |
177 | |
178 | =head1 PROJECT WORKFLOW |
179 | |
180 | For longer lasting branches, we use a subversion style branch layout, where |
181 | master is routinely merged into the branch. Rebasing is allowed as long as all |
5af926eb |
182 | the branch contributors are using C<git pull --rebase> properly. |
04437dba |
183 | |
184 | C<commit --amend>, C<rebase --interactive>, etc. are not allowed, and should |
185 | only be done in topic branches. Committing to master is still done with the |
186 | same review process as a topic branch, and the branch must merge as a fast |
187 | forward. |
188 | |
9840bb38 |
189 | This is pretty much the way we're doing branches for large-ish things right |
04437dba |
190 | now. |
191 | |
192 | Obviously there is no technical limitation on the number of branches. You can |
193 | freely create topic branches off of project branches, or sub projects inside |
194 | larger projects freely. Such branches should incorporate the name of the branch |
195 | they were made off so that people don't accidentally assume they should be |
196 | merged into master: |
197 | |
198 | git checkout -b my-project--topic/foo my-project |
199 | |
200 | (unfortunately Git will not allow C<my-project/foo> as a branch name if |
201 | C<my-project> is a valid ref). |
202 | |
203 | =head1 THE "PU" BRANCH |
204 | |
205 | To make things easier for longer lived branches (whether topics or projects), |
206 | the 'pu' branch is basically what happens if you merge all of the branches and |
207 | topics together with master. |
208 | |
209 | We can update this as necessary (e.g. on a weekly basis if there is merit), |
210 | notifying the authors of the respective branches if their branches did not merge |
211 | (and why). |
212 | |
213 | To update 'pu': |
214 | |
215 | git checkout pu |
216 | git remote update |
217 | git reset --hard origin/master |
218 | git merge @all_the_branches |
219 | |
220 | If the merge is clean, 'pu' is updated with C<push --force>. |
221 | |
222 | If the merge is not clean, the offending branch is removed from |
223 | C<@all_the_branches>, with a small note of the conflict, and we try again. |
224 | |
225 | The authors of the failed branches should be told to try to merge their branch |
226 | into 'pu', to see how their branch interacts with other branches. |
227 | |
228 | 'pu' is probably broken most of the time, but lets us know how the different |
229 | branches interact. |
230 | |
231 | =head1 BRANCH ARCHIVAL |
232 | |
233 | Merged branches should be deleted. |
234 | |
235 | Failed branches may be kept, but consider moving to refs/attic/ (e.g. |
236 | http://danns.co.uk/node/295) to keep git branch -l current. |
237 | |
238 | Any branch that could still realistically be merged in the future, even if it |
239 | hasn't had work recently, should not be archived. |
240 | |
600f7f85 |
241 | =head1 TESTS, TESTS, TESTS |
242 | |
d85337ff |
243 | If you write I<any> code for Moose or Class::MOP, you B<must> add |
244 | tests for that code. If you do not write tests then we cannot |
04437dba |
245 | guarantee your change will not be removed or altered at a later date, |
246 | as there is nothing to confirm this is desired behavior. |
d85337ff |
247 | |
248 | If your code change/addition is deep within the bowels of |
249 | Moose/Class::MOP and your test exercises this feature in a non-obvious |
250 | way, please add some comments either near the code in question or in |
251 | the test so that others know. |
600f7f85 |
252 | |
d85337ff |
253 | We also greatly appreciate documentation to go with your changes, and |
254 | an entry in the Changes file. Make sure to give yourself credit! |
600f7f85 |
255 | |
d85337ff |
256 | =head1 BACKWARDS COMPATIBILITY |
600f7f85 |
257 | |
04437dba |
258 | Change is inevitable, and Moose is not immune to this. We do our best |
86b96832 |
259 | to maintain backwards compatibility, but we do not want the code base |
d85337ff |
260 | to become overburdened by this. This is not to say that we will be |
261 | frivolous with our changes, quite the opposite, just that we are not |
262 | afraid of change and will do our best to keep it as painless as |
263 | possible for the end user. |
600f7f85 |
264 | |
04437dba |
265 | The rule is that if you do something that is not backwards compatible, you |
266 | B<must> do I<at least> one deprecation cycle (more if it is larger change). |
267 | For really larger or radical changes dev releases may be needed as well (the |
268 | Cabal will decide on this on a case-per-case basis). |
600f7f85 |
269 | |
04437dba |
270 | The preference with regard to deprecation is to warn loudly and often so that |
271 | users will have time to fix their usages. |
600f7f85 |
272 | |
d85337ff |
273 | All backwards incompatible changes B<must> be documented in |
04437dba |
274 | L<Moose::Manual::Delta>. Make sure to document any useful tips or workarounds |
275 | for the change in that document. |
600f7f85 |
276 | |
277 | =head1 AUTHOR |
278 | |
279 | Stevan Little E<lt>stevan@iinteractive.comE<gt> |
280 | |
04437dba |
281 | Chris (perigrin) Prather |
282 | |
283 | Yuval (nothingmuch) Kogman |
284 | |
600f7f85 |
285 | =head1 COPYRIGHT AND LICENSE |
286 | |
287 | Copyright 2009 by Infinity Interactive, Inc. |
288 | |
289 | L<http://www.iinteractive.com> |
290 | |
291 | This library is free software; you can redistribute it and/or modify |
292 | it under the same terms as Perl itself. |
293 | |
d85337ff |
294 | =cut |