view release on metacpan or  search on metacpan

docs/SubmittingPatches.pod  view on Meta::CPAN

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.

Do not PGP sign your patch, at least for now.  Most likely, your
maintainer or other people on the list would not have your PGP
key and would not bother obtaining it anyway.  Your patch is not
judged by who you are; a good patch from an unknown origin has a
far better chance of being accepted than a patch from a known,
respected origin that is done poorly or does incorrect things.

If you really really really really want to do a PGP signed
patch, format it as "multipart/signed", not a text/plain message
that starts with '-----BEGIN PGP SIGNED MESSAGE-----'.  That is
not a text/plain, it's something else.

Unless your patch is a very trivial and an obviously correct one,
first send it with "To:" set to the RT email (or mailing list), with "cc:"
listing people who are involved in the area you are touching (the output from
"git blame $path" and "git shortlog --no-merges $path" would help to
identify them), to solicit comments and reviews.  After the list
reached a consensus that it is a good idea to apply the patch, re-send
it with "To:" set to the maintainer and optionally "cc:" the list for
inclusion.  Do not forget to add trailers such as "Acked-by:",
"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as
necessary.

=head2 (4) Sign your work

To improve tracking of who did what, we've borrowed the
"sign-off" procedure from the Linux kernel project on patches
that are being emailed around.  Although this project is a lot
smaller it is a good discipline to follow it.

The sign-off is a simple line at the end of the explanation for
the patch, which certifies that you wrote it or otherwise have
the right to pass it on as a open-source patch.  The rules are
pretty simple: if you can certify the below:

        Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) The contribution was created in whole or in part by me and I
            have the right to submit it under the open source license
            indicated in the file; or

        (b) The contribution is based upon previous work that, to the best
            of my knowledge, is covered under an appropriate open source
            license and I have the right under that license to submit that
            work with modifications, whether created in whole or in part
            by me, under the same open source license (unless I am
            permitted to submit under a different license), as indicated
            in the file; or

        (c) The contribution was provided directly to me by some other
            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.

then you just add a line saying

	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.

Notice that you can place your own Signed-off-by: line when
forwarding somebody else's patch with the above rules for
D-C-O.  Indeed you are encouraged to do so.

Also notice that a real name is used in the Signed-off-by: line. Please
don't hide your real name.

Some people also put extra tags at the end.

"Acked-by:" says that the patch was reviewed by the person who
is more familiar with the issues and the area the patch attempts
to modify.  "Tested-by:" says the patch was tested by the person
and found to have the desired effect.

=head1 An ideal patch flow

Here is an ideal patch flow for this project the current maintainer
suggests to the contributors:

=over 4

=item 0. You come up with an itch.  You code it up.

E<10>

=item 1. Send it to the bug tracker and cc people who may need to know about
the change.

E<10>
The people who may need to know are the ones whose
code you are butchering.  These people happen to be the ones who are most
likely to be knowledgeable enough to help you, but they have no obligation to
help you (i.e. you ask for help, don't demand).  "git log -p --
$area_you_are_modifying" would help you find out who they are.

=item 2. You get comments and suggestions for improvements.  You may even
get them in a "on top of your change" patch form.

E<10>

=item 3. Polish, refine, and re-send to the the people who spend their
time to improve your patch.  Go back to step (2).

E<10>

=item 4. A topic branch is created with the patch and is merged to 'next',
and cooked further and eventually graduates to 'master'.

=back