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