|
| 1 | +How to contribute patches to the PPP project. |
| 2 | +============================================= |
| 3 | + |
| 4 | +The PPP project source code is maintained in a Git repository, which |
| 5 | +is publicly available at |
| 6 | + |
| 7 | +git://git.ozlabs.org/~paulus/ppp.git |
| 8 | + |
| 9 | +and |
| 10 | + |
| 11 | +https://github.com/paulusmack/ppp.git |
| 12 | + |
| 13 | +The [email protected] mailing list is a suitable place to |
| 14 | +discuss issues relating to the PPP code and to post patches. |
| 15 | + |
| 16 | +Although there is a copy of the repository on github.com, the PPP |
| 17 | +project is not a "github project", in the sense that the development |
| 18 | +of the code does not depend on github infrastructure. In particular, |
| 19 | +patch descriptions should be understandable without reference to any |
| 20 | +github.com web page. Thus, patches or commits whose description |
| 21 | +consists only of something like "Closes #123" will be rejected. See |
| 22 | +below for the minimum standards for patch descriptions. |
| 23 | + |
| 24 | +There are two ways in which patches can be submitted for review: |
| 25 | + |
| 26 | +1. Post the patch on the [email protected] mailing list. This |
| 27 | + is my preferred way to receive patches, because it provides more |
| 28 | + opportunity for other interested people to review the patches. |
| 29 | + |
| 30 | +2. Create a pull request on github.com. However, please don't make |
| 31 | + the mistake of creating a commit with a minimal commit message and |
| 32 | + then explaining the rationale for the change in the pull request. |
| 33 | + Put the rationale in the commit message. |
| 34 | + |
| 35 | +Requirements for patch/commit description |
| 36 | +----------------------------------------- |
| 37 | + |
| 38 | +The description on a patch, which becomes the commit message in the |
| 39 | +resulting commit, should describe the reason why the change is being |
| 40 | +made. If it fixes a bug, it should describe the bug in enough detail |
| 41 | +for the reader to understand why and how the change being made fixes |
| 42 | +the bug. If it adds a feature, it should describe the feature and how |
| 43 | +it might be used and why it would be desirable to have the feature. |
| 44 | + |
| 45 | +Normally the patch description should be a few paragraphs in length -- |
| 46 | +it can be longer for a really subtle bug or complex feature, or |
| 47 | +shorter for obvious or trivial changes such as fixing spelling |
| 48 | +mistakes. |
| 49 | + |
| 50 | +The first line of the commit message is the "headline", corresponding |
| 51 | +to the subject line of an emailed patch. If the patch is concerned |
| 52 | +with one particular area of the package, it is helpful to put that at |
| 53 | +the beginning, followed by a colon (':'), for example, "pppd: Fix bug |
| 54 | +in vslprintf". The remainder of the headline should be a sentence and |
| 55 | +should start with a capital letter. |
| 56 | + |
| 57 | +Note that as maintainer I will edit the headline or the commit message |
| 58 | +if necessary to make it clearer or to fix spelling or grammatical |
| 59 | +errors. For a github pull request I may cherry-pick the commits and |
| 60 | +modify their commit messages. |
| 61 | + |
| 62 | +References to information on web sites are permitted provided that the |
| 63 | +full URL is given, and that reference to the web site is not essential |
| 64 | +for understanding the change being made. For example, you can refer |
| 65 | +to a github issue provided that you also put the essential details of |
| 66 | +the issue in the commit message, and put the full URL for the issue, |
| 67 | +not just the issue number. |
| 68 | + |
| 69 | +Signoff |
| 70 | +------- |
| 71 | + |
| 72 | +In order to forestall possible (though unlikely) future legal |
| 73 | +problems, this project requires a "Signed-off-by" line on all |
| 74 | +non-trivial patches, with a real name (not just initials, and no |
| 75 | +pseudonyms). Signing off indicates that you certify that your patch |
| 76 | +meets the 'Developer's Certificate of Origin' below (taken from the |
| 77 | +DCO 1.1 in the Linux kernel source tree). |
| 78 | + |
| 79 | +Developer's Certificate of Origin |
| 80 | +--------------------------------- |
| 81 | + |
| 82 | +By making a contribution to this project, I certify that: |
| 83 | + |
| 84 | + (a) The contribution was created in whole or in part by me and I |
| 85 | + have the right to submit it under the open source license |
| 86 | + indicated in the file; or |
| 87 | + |
| 88 | + (b) The contribution is based upon previous work that, to the best |
| 89 | + of my knowledge, is covered under an appropriate open source |
| 90 | + license and I have the right under that license to submit that |
| 91 | + work with modifications, whether created in whole or in part |
| 92 | + by me, under the same open source license (unless I am |
| 93 | + permitted to submit under a different license), as indicated |
| 94 | + in the file; or |
| 95 | + |
| 96 | + (c) The contribution was provided directly to me by some other |
| 97 | + person who certified (a), (b) or (c) and I have not modified |
| 98 | + it. |
| 99 | + |
| 100 | + (d) I understand and agree that this project and the contribution |
| 101 | + are public and that a record of the contribution (including all |
| 102 | + personal information I submit with it, including my sign-off) is |
| 103 | + maintained indefinitely and may be redistributed consistent with |
| 104 | + this project or the open source license(s) involved. |
| 105 | + |
0 commit comments