Debian Codegraph @

SubmittingPatches

raw
1 Checklist (and a short version for the impatient):
2
3 Commits:
4
5 - make commits of logical units
6 - check for unnecessary whitespace/identation/documentation
7 with "git diff --check" and maintainer tests for each commit
8 - do not check in commented out code or unneeded files
9 - provide a meaningful commit message
10 - the first line of the commit message should be a short
11 description and should skip the full stop
12 - if you want your work included, add a
13 "Signed-off-by: Your Name <[email protected]>" line to the
14 commit message (or just use the option "-s" when
15 committing) to confirm that you agree to the Developer's
16 Certificate of Origin (below)
17 - make sure that you have tests for the bug you are fixing
18 - make sure that the test suite passes after your commit
19
20 Patches:
21
22 - use "git format-patch -M" to create the patch
23
24 - send the patch to ([email protected]) If you use
25 git-send-email(1), please test it first by sending email to
26 yourself.
27
28 - patches may also be sent to the RT queue for the module on
29 rt.cpan.org; please only create one ticket for each
30 independent change or closely related series of independent
31 changes.
32
33 Pull requests:
34
35 - if you use github, use the 'pull request' option and select
36 'Catalyst' as the recipient. Please do remember to sign-off
37 your changes!
38
39 ----
40
41 Developer's Certificate of Origin 1.2-gnu
42
43 By making a contribution to this project, I certify that:
44
45 (a) The contribution was created in whole or in part by me and I
46 have the right to submit it under the license indicated in the
47 file; or
48
49 (b) The contribution is based upon previous work that, to the best
50 of my knowledge, is covered under an compatible license and I
51 have the right under that license to submit that work with
52 modifications, whether created in whole or in part by me, under
53 the same license (unless I am permitted to submit under a
54 different license), as indicated in the file; or
55
56 (c) The contribution was provided directly to me by some other
57 person who certified (a), (b) or (c) and I have not modified it.
58
59 (d) I understand and agree that this project and the contribution
60 are public and that a record of the contribution (including all
61 personal information I submit with it, including my sign-off) is
62 maintained indefinitely and may be redistributed consistent with
63 this project or the license(s) involved.
64
65 ----
66
67 These patch guidelines are intended to help you help us maintain the
68 software. We are interested in all submissions, however we may not
69 have time to make the changes you submit meet the code base standard.
70
71
72 Detailed information:
73
74 (1) Make separate commits for logically separate changes.
75
76 Unless your patch is really trivial, you should not be sending
77 out a patch that was generated between your working tree and
78 your commit head. Instead, always make a commit with complete
79 commit message and generate a series of patches from your
80 repository. It is a good discipline.
81
82 Describe the technical detail of the change(s).
83
84 The guiding principle for change messages is that they should only
85 describe the change that they are making. There should be a little
86 story:
87
88 1. why the change must happen (the motivation)
89
90 2. what the code used to do, if appropriate (old behaviour)
91
92 3. an outline of the new approach, sparing excessive details (new
93 behaviour)
94
95 They should always be written from the perspective that someone has
96 just run 'git annotate' and landed on this commit; that person has no
97 idea whatsoever about related commits in time. The description should
98 be written in the present tense; with no reference to terms like "this
99 patch".
100
101 If your description starts to get too long, that's a sign that you
102 probably need to split up your commit to finer grained pieces.
103
104
105 (1a) Test your changes
106
107 Your changes should include tests which demonstrate and hopefully test
108 corner cases of your new additions. If you have difficulty writing
109 these, please submit anyway but tests will help us be sure that your
110 code works and is suitable for inclusion.
111
112 Ideally, the new tests should fail on the old code, pass on the new
113 code, and test the documented functionality.
114
115
116 (1b) Whitespace, indentation, documentation and copyright boilerplate
117
118 There are tests which check that the indentation matches that which
119 'perltidy' will produce for the file. Please use them to check that
120 you are conforming to the indentation style of the project. This will
121 involve installing 'perltidy', and setting an environment variable.
122 The style is specifically chosen to allow readers to choose their own
123 tab width setting without breaking the appearance of the code, and to
124 make merging changes easier.
125
126 In terms of documentation, we also have a rule that all object methods
127 must be documented, or at least mentioned in the SYNOPSIS section of
128 the man page/perldoc for that module. The exception to this is
129 internal functions, which are marked by starting with an underscore.
130 Again, there is a test script for this which only runs with a
131 particular environment variable set. Running the test suite using
132 'make test' will tell you what you need to set.
133
134 It is also required that every Perl program contains a brief copyright
135 statement, and there is a test for that too.
136
137
138 (1c) Be nice to Perl 5.8.x
139
140 This codebase is currently designed to run on older perls, ie 5.8.x;
141 though we are likely to soon be making 5.10.0 a minimum requirement.
142 So currently, do not use 5.10+ features such as //-defined-or,
143 smartmatch or newer regex-engine features. We will also endeavour to
144 test the code base on the latest blead and Perl maint branches.
145
146
147 (2) Generate your patch using git tools out of your commits.
148
149 git based diff tools (git, StGIT, etc) generate unidiff which is the
150 preferred format.
151
152 You do not have to be afraid to use -M option to "git diff" or
153 "git format-patch", if your patch involves file renames. The
154 receiving end can handle them just fine.
155
156 Please make sure your patch does not include any extra files
157 which do not belong in a patch submission. Make sure to review
158 your patch after generating it, to ensure accuracy. Before
159 sending out, please make sure it cleanly applies to the "master"
160 branch head. If you are preparing a work based on "next" branch,
161 that is fine, but please mark it as such.
162
163
164 (3) Agreeing to the DCO
165
166 The "Sign-off" procedure from git.git and linux-2.6.git is used for
167 this project. This Sign-off indicates _copyright_ conformance only,
168 and is the only strict requirement for submissions.
169
170 If you are submitting many changes and are worried about potential
171 patent infringement lawsuits, please contact us for a copyright
172 assignment agreement so that we can take formal ownership of your
173 contributions. However this is not necessary for casual submissions,
174 or for those who do not worry about such things.
175
176 If you want to indicate your change has been reviewed by someone, you
177 can use 'Acked-by:'
178
179
180 (4) Sending it in.
181
182 As there is not currently a mailing list for this program, please
183 submit via one of the following means:
184
185 * fork the project on github
186 (http://github.com/st3vil/crypt-password) and send a pull
187 request.
188
189 * Log a ticket at rt.cpan.org under the queue for 'Crypt::Password'
190 (if you must)