docs/contribute.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 Contributing to OpenADK
   5 =======================
   6
   7 If you want to contribute to OpenADK, you will need a git view of
   8 the project. Refer to xref:getting-openadk[] to get it.
   9
  10 Currently a mail to wbx@openadk.org is the central place for contribution.
  11
  12 [[submitting-patches]]
  13 Submitting patches
  14 ------------------
  15
  16 When your changes are done, and committed in your local git view,
  17 _rebase_ your development branch on top of the upstream tree before
  18 generating the patch set. To do so, run:
  19
  20 ---------------------
  21 $ git fetch --all --tags
  22 $ git rebase origin/master
  23 ---------------------
  24
  25 Here, you are ready to generate then submit your patch set.
  26
  27 To generate it, run:
  28
  29 ---------------------
  30 $ git format-patch -M -n -s origin/master
  31 ---------------------
  32
  33 This will generate patch files automatically adding the +Signed-off-by+ line.
  34
  35 Once patch files are generated, you can review/edit the commit message
  36 before submitting them using your favorite text editor.
  37
  38 Lastly, send/submit your patch set to the OpenADK developer:
  39
  40 ---------------------
  41 $ git send-email --to wbx@openadk.org *.patch
  42 ---------------------
  43
  44 Note that +git+ should be configured to use your mail account.
  45 To configure +git+, see +man git-send-email+ or google it.
  46
  47 Make sure posted *patches are not line-wrapped*, otherwise they cannot
  48 easily be applied. In such a case, fix your e-mail client, or better,
  49 use +git send-email+ to send your patches.
  50
  51 Cover letter
  52 ~~~~~~~~~~~~
  53
  54 If you want to present the whole patch set in a separate mail, add
  55 +--cover-letter+ to the +git format-patch+ command (see +man
  56 git-format-patch+ for further information). This will generate a
  57 template for an introduction e-mail to your patch series.
  58
  59 A 'cover letter' may be useful to introduce the changes you propose
  60 in the following cases:
  61
  62 * large number of commits in the series;
  63
  64 * deep impact of the changes in the rest of the project;
  65
  66 * RFC footnote:[RFC: (Request for comments) change proposal];
  67
  68 * whenever you feel it will help presenting your work, your choices,
  69   the review process, etc.
  70
  71 [[reporting-bugs]]
  72 Reporting issues/bugs, get help
  73 -------------------------------
  74
  75 Try to think as if you were trying to help someone else; in
  76 that case, what would you need?
  77
  78 Here is a short list of details to provide in such case:
  79
  80 * host machine (OS/release)
  81 * git version of OpenADK
  82 * target for which the build fails
  83 * package(s) which the build fails
  84 * the command that fails and its output
  85 * the make.log file, generated when make v is used
  86 * any information you think that may be relevant
  87
  88 Additionally, you can add the +.config+ file.