differs substantially from the prior version, are all good things
to have.
-Make sure that you have tests for the bug you are fixing.
+Make sure that you have tests for the bug you are fixing. See
+t/README for guidance.
When adding a new feature, make sure that you have new tests to show
the feature triggers the new behaviour when it should, and to show the
test suite passes after your commit. Do not forget to update the
documentation to describe the updated behaviour.
-Oh, another thing. I am picky about whitespaces. Make sure your
+Speaking of the documentation, it is currently a liberal mixture of US
+and UK English norms for spelling and grammar, which is somewhat
+unfortunate. A huge patch that touches the files all over the place
+only to correct the inconsistency is not welcome, though. Potential
+clashes with other changes that can result from such a patch are not
+worth it. We prefer to gradually reconcile the inconsistencies in
+favor of US English, with small and easily digestible patches, as a
+side effect of doing some other real work in the vicinity (e.g.
+rewriting a paragraph for clarity, while turning en_UK spelling to
+en_US). Obvious typographical fixes are much more welcomed ("teh ->
+"the"), preferably submitted as independent patches separate from
+other documentation changes.
+
+Oh, another thing. We are picky about whitespaces. Make sure your
changes do not trigger errors with the sample pre-commit hook shipped
in templates/hooks--pre-commit. To help ensure this does not happen,
run git diff --check on your changes before you commit.
You often want to add additional explanation about the patch,
other than the commit message itself. Place such "cover letter"
-material between the three dash lines and the diffstat. Git-notes
-can also be inserted using the `--notes` option.
+material between the three-dash line and the diffstat. For
+patches requiring multiple iterations of review and discussion,
+an explanation of changes between each iteration can be kept in
+Git-notes and inserted automatically following the three-dash
+line via `git format-patch --notes`.
Do not attach the patch as a MIME attachment, compressed or not.
Do not let your e-mail client send quoted-printable. Do not let
person who certified (a), (b) or (c) and I have not modified
it.
- (d) I understand and agree that this project and the contribution
- are public and that a record of the contribution (including all
- personal information I submit with it, including my sign-off) is
- maintained indefinitely and may be redistributed consistent with
- this project or the open source license(s) involved.
+ (d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
then you just add a line saying
- Signed-off-by: Random J Developer <random@developer.example.org>
+ Signed-off-by: Random J Developer <random@developer.example.org>
This line can be automatically added by Git if you run the git-commit
command with the -s option.
spend their time to improve your patch. Go back to step (2).
(4) The list forms consensus that the last round of your patch is
- good. Send it to the list and cc the maintainer.
+ good. Send it to the maintainer and cc the list.
(5) A topic branch is created with the patch and is merged to 'next',
and cooked further and eventually graduates to 'master'.