This is an automated email from the git hooks/post-receive script. abe pushed a commit to annotated tag 2.006001 in repository libdist-zilla-plugin-test-podspelling-perl.
commit b119e0650a5fc5377d31f99057c5abd86e61c0e9 Author: Caleb Cushing <[email protected]> Date: Sat Sep 7 03:11:46 2013 -0500 add CONTRIBUTING file fixes GH #15 Signed-off-by: Caleb Cushing <[email protected]> --- CONTRIBUTING | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) diff --git a/CONTRIBUTING b/CONTRIBUTING new file mode 100644 index 0000000..5fdcabd --- /dev/null +++ b/CONTRIBUTING @@ -0,0 +1,220 @@ +Checklist + +(and a short version for the impatient): + +Branching: +- git checkout origin/master -b my-feature-or-bug + - ensure that you start on the right branch `build/master` is the "default" + branch, but patches should be based on `master`. It's generally safe to + patch against `build/master` so long as you don't attempt to modify + generated files or add files that exist in `master` that are intentionally + stripped from the build. +- do not include more than one feature or bug in your branch + +Commits: +- make sure that the test suite passes after your commit. This distribution + is built with Dist::Zilla ensure that running `dzil test` passes. You are + responsible for ensuring that generated, hand written and author tests pass. +- make sure that you have tests for the bug you are fixing +- make commits of logical units +- check for unnecessary whitespace with "git diff --check" before committing +- do not check in commented out code or unneeded files +- the first line of the commit message should be a short description and + should skip the full stop +- the body should provide a meaningful commit message, which: + - uses the imperative, present tense: "change", not "changed" or "changes". + - includes motivation for the change, and contrasts its implementation with + previous behaviour +- if you want your work included in the main repository, add a "Signed-off-by: + Your Name <[email protected]>" line to the commit message (or just use the + option "-s" when committing) to confirm that you agree to the Developer's + Certificate of Origin + +Patch: +- if you change, add, or remove any features or make some other user + interface change, the associated documentation should be updated as well. +- if your name is not writable in ASCII, make sure that you send the + patch in the correct encoding. + +Long version: + +I started reading over the SubmittingPatches document for git, +primarily because I wanted to have a document similar to it for +my projects to make sure people understand what they are doing +when they write "Signed-off-by" line. + +But the patch submission requirements are a lot more relaxed +here on the technical/contents front, because my projects are +thousand times smaller ;-). So here is only the relevant bits. + + +(0) Decide what to base your work on. + +In general, always base your work on the oldest branch that your +change is relevant to. + +* A bugfix should be based on 'maint' in general. If the bug is not +present in 'maint', base it on 'master'. For a bug that's not yet +in 'master', find the topic that introduces the regression, and +base your work on the tip of the topic. If a 'maint' branch is not present +base it on master. + +* A new feature should be based on 'master' in general. If the new +feature depends on a topic that is in 'pu', but not in 'master', base your +work on the tip of that topic. + +* Corrections and enhancements to a topic not yet in 'master' should be +based on the tip of that topic. If the topic has not been merged to 'next', +it's alright to add a note to squash minor corrections into the series. + +* In the exceptional case that a new feature depends on several topics +not in 'master', start working on 'next' or 'pu' privately and send out +patches for discussion. Before the final merge, you may have to wait until +some of the dependent topics graduate to 'master', and rebase your work. + +To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The second parent of this +commit is the tip of the topic branch. + + +(1) Make separate commits for logically separate changes. + +Unless your patch is really trivial, you should not be sending +out a patch that was generated between your working tree and +your commit head. Instead, always make a commit with complete +commit message and generate a series of patches from your +repository. It is a good discipline. + +Describe the technical detail of the change(s). + +If your description starts to get too long, that's a sign that you +probably need to split up your commit to finer grained pieces. +That being said, patches which plainly describe the things that +help reviewers check the patch, and future maintainers understand +the code, are the most beautiful patches. Descriptions that summarise +the point in the subject well, and describe the motivation for the +change, the approach taken by the change, and if relevant how this +differs substantially from the prior version, can be found on Usenet +archives back into the late 80's. Consider it like good Netiquette, +but for code. + +Oh, another thing. I am 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. + + +(2) Generate your patch using git tools out of your commits. + +git based diff tools (git, Cogito, and StGIT included) generate +unidiff which is the preferred format. + +You do not have to be afraid to use -M option to "git diff" or +"git format-patch", if your patch involves file renames. The +receiving end can handle them just fine. + +Please make sure your patch does not include any extra files +which do not belong in a patch submission. Make sure to review +your patch after generating it, to ensure accuracy. Before +sending out, please make sure it cleanly applies to the "master" +branch head. If you are preparing a work based on "next" branch, +that is fine, but please mark it as such. + +(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 <[email protected]> + +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. + + +An ideal patch flow + +Here is an ideal patch flow for this project the current maintainer +suggests to the contributors: + +0. You come up with an itch. You code it up. +1. Send it to the bug tracker and cc people who may need to know about + the change. + + 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. + +2. You get comments and suggestions for improvements. You may even + get them in a "on top of your change" patch form. + +3. Polish, refine, and re-send to the the people who spend their + time to improve your patch. Go back to step (2). + +4. A topic branch is created with the patch and is merged to 'next', + and cooked further and eventually graduates to 'master'. + +In any time between the (2)-(3) cycle, the maintainer may pick it up +from the list and queue it to 'pu', in order to make it easier for +people play with it without having to pick up and apply the patch to +their trees themselves. + + +Know the status of your patch after submission + +* You can use Git itself to find out when your patch is merged in +master. 'git pull --rebase' will automatically skip already-applied +patches, and will let you know. This works only if you rebase on top +of the branch in which your patch has been merged (i.e. it will not +tell you if your patch is merged in pu if you rebase on top of +master). -- Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libdist-zilla-plugin-test-podspelling-perl.git _______________________________________________ Pkg-perl-cvs-commits mailing list [email protected] http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-perl-cvs-commits
