| 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) |