Submitting-patches.md

   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 linux-ppp@vger.kernel.org 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 linux-ppp@vger.kernel.org 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