doc/HowToContribute.txt

   1 Checklist (and a short version for the impatient):\r
   2 \r
   3         Commits:\r
   4 \r
   5         - make commits of (small) logical units\r
   6         - check for unnecessary whitespace with "git diff --check"\r
   7           before committing\r
   8         - do not check in commented out code or unneeded files\r
   9         - the first line of the commit message should be a short\r
  10           description and should skip the full stop. If it is about a\r
  11           bugreport/issue, prepend "Fixed issue #NUMBER: " to the subject.\r
  12         - the body should provide a meaningful commit message, which:\r
  13           . explains the problem the change tries to solve, iow, what\r
  14             is wrong with the current code without the change.\r
  15           . justifies the way the change solves the problem, iow, why\r
  16             the result with the change is better.\r
  17           . alternate solutions considered but discarded, if any.\r
  18         - describe changes in imperative mood, e.g. "make xyzzy do frotz"\r
  19           instead of "[This patch] makes xyzzy do frotz" or "[I] changed\r
  20           xyzzy to do frotz", as if you are giving orders to the codebase\r
  21           to change its behaviour.\r
  22         - try to make sure your explanation can be understood without\r
  23           external resources. Instead of giving a URL to a mailing list\r
  24           archive, summarize the relevant points of the discussion.\r
  25         - add a "Signed-off-by: Your Name <you@example.com>" line to the\r
  26           commit message (or just use the option "-s" when committing)\r
  27           to confirm that you agree to the Developer's Certificate of Origin\r
  28 \r
  29         Submission:\r
  30         \r
  31         - open an issue on http://code.google.com/p/tortoisegit/ or go to an\r
  32           issue you want to fix. Then you have one of the following options:\r
  33           . attach a patch there\r
  34           . provide a link to a branch you want the maintainers to pull from\r
  35           . open a github pull request and put the link into the issue\r
  36 \r
  37 Longer version:\r
  38 \r
  39 (0) Make separate commits for logically separate changes.\r
  40 \r
  41 Unless your patch is really trivial, you should not be sending\r
  42 out a patch that was generated between your working tree and\r
  43 your commit head.  Instead, always make a commit with complete\r
  44 commit message and generate a series of patches from your\r
  45 repository.\r
  46 \r
  47 Give an explanation for the change(s) that is detailed enough so\r
  48 that people can judge if it is good thing to do, without reading\r
  49 the actual patch text to determine how well the code does what\r
  50 the explanation promises to do.\r
  51 \r
  52 If your description starts to get too long, that's a sign that you\r
  53 probably need to split up your commit to finer grained pieces.\r
  54 That being said, patches which plainly describe the things that\r
  55 help reviewers check the patch, and future maintainers understand\r
  56 the code, are the most beautiful patches.  Descriptions that summarise\r
  57 the point in the subject well, and describe the motivation for the\r
  58 change, the approach taken by the change, and if relevant how this\r
  59 differs substantially from the prior version, are all good things\r
  60 to have.\r
  61 \r
  62 Oh, another thing. We are picky about whitespaces. To help ensure this\r
  63 does not happen, run git diff --check on your changes before you commit.\r
  64 \r
  65 \r
  66 (1a) Generate your patch using git tools out of your commits (Patch serial)\r
  67 \r
  68 git based diff tools generate unidiff which is the preferred format.\r
  69 \r
  70 Please make sure your patch does not include any extra files\r
  71 which do not belong in a patch submission.  Make sure to review\r
  72 your patch after generating it, to ensure accuracy.  Before\r
  73 sending out, please make sure it cleanly applies to the "master"\r
  74 branch head.\r
  75 \r
  76 \r
  77 (1b) Create a pull request\r
  78 \r
  79 Push your changes to a public repository. Use a brief branch name\r
  80 describing your changes.\r
  81 \r
  82 Please make sure your pull request does not include any extra files\r
  83 which do not belong in a submission.  Make sure to review your patch\r
  84 after generating it, to ensure accuracy.\r
  85 \r
  86 There is no need to generate a "formal" pull request. The URL and\r
  87 branchname is necessary - or create a github pull request\r
  88 (https://github.com/TortoiseGit).\r
  89 \r
  90 \r
  91 (2) Sign your work\r
  92 \r
  93 To improve tracking of who did what, we've borrowed the\r
  94 "sign-off" procedure from the Linux kernel project on patches\r
  95 that are being emailed around.  Although TortoiseGit is a lot\r
  96 smaller project it is a good discipline to follow it.\r
  97 \r
  98 The sign-off is a simple line at the end of the explanation for\r
  99 the patch, which certifies that you wrote it or otherwise have\r
 100 the right to pass it on as a open-source patch.  The rules are\r
 101 pretty simple: if you can certify the below:\r
 102 \r
 103         Developer's Certificate of Origin 1.1\r
 104 \r
 105         By making a contribution to this project, I certify that:\r
 106 \r
 107         (a) The contribution was created in whole or in part by me and I\r
 108             have the right to submit it under the open source license\r
 109             indicated in the file; or\r
 110 \r
 111         (b) The contribution is based upon previous work that, to the best\r
 112             of my knowledge, is covered under an appropriate open source\r
 113             license and I have the right under that license to submit that\r
 114             work with modifications, whether created in whole or in part\r
 115             by me, under the same open source license (unless I am\r
 116             permitted to submit under a different license), as indicated\r
 117             in the file; or\r
 118 \r
 119         (c) The contribution was provided directly to me by some other\r
 120             person who certified (a), (b) or (c) and I have not modified\r
 121             it.\r
 122 \r
 123         (d) I understand and agree that this project and the contribution\r
 124             are public and that a record of the contribution (including all\r
 125             personal information I submit with it, including my sign-off) is\r
 126             maintained indefinitely and may be redistributed consistent with\r
 127             this project or the open source license(s) involved.\r
 128 \r
 129 then you just add a line saying\r
 130 \r
 131         Signed-off-by: Random J Developer <random@developer.example.org>\r
 132 \r
 133 This line can be automatically added by Git and TortoiseGit.\r
 134 \r
 135 Also notice that a real name is used in the Signed-off-by: line. Please\r
 136 don't hide your real name.\r
 137 \r
 138 If you like, you can put extra tags at the end:\r
 139 \r
 140 1. "Reported-by:" is used to credit someone who found the bug that\r
 141    the patch attempts to fix.\r
 142 2. "Acked-by:" says that the person who is more familiar with the area\r
 143    the patch attempts to modify liked the patch.\r
 144 3. "Reviewed-by:", unlike the other tags, can only be offered by the\r
 145    reviewer and means that she is completely satisfied that the patch\r
 146    is ready for application.  It is usually offered only after a\r
 147    detailed review.\r
 148 4. "Tested-by:" is used to indicate that the person applied the patch\r
 149    and found it to have the desired effect.\r
 150 \r
 151 You can also create your own tag or use one that's in common usage\r
 152 such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:".\r
 153 \r
 154 ------------------------------------------------\r
 155 An ideal patch flow\r
 156 \r
 157 Here is an ideal patch flow for this project the current maintainer\r
 158 suggests to the contributors:\r
 159 \r
 160  (0) You come up with an itch.  You code it up.\r
 161 \r
 162  (1) Open an issue on http://code.google.com/p/tortoisegit/ or attach\r
 163      your changes to another already reported issue. Attach the patches\r
 164      or provide a pull request (URL branch) there.\r
 165 \r
 166  (2) You get comments and suggestions for improvements.  You may\r
 167      even get them in a "on top of your change" patch form.\r
 168 \r
 169  (3) Polish, refine, and re-send.  Go back to step (2).\r
 170 \r
 171  (4) The patch will be applied to master.\r