source/libs/pixman/pixman-src/README

   1 Pixman is a library that provides low-level pixel manipulation
   2 features such as image compositing and trapezoid rasterization.
   3
   4 Questions, bug reports and patches should be directed to the pixman
   5 mailing list:
   6
   7         http://lists.freedesktop.org/mailman/listinfo/pixman
   8
   9 You can also file bugs at
  10
  11         https://bugs.freedesktop.org/enter_bug.cgi?product=pixman
  12
  13 For real time discussions about pixman, feel free to join the IRC
  14 channels #cairo and #xorg-devel on the FreeNode IRC network.
  15
  16
  17 Contributing
  18 ------------
  19
  20 In order to contribute to pixman, you will need a working knowledge of
  21 the git version control system. For a quick getting started guide,
  22 there is the "Everyday Git With 20 Commands Or So guide"
  23
  24         http://www.kernel.org/pub/software/scm/git/docs/everyday.html
  25
  26 from the Git homepage. For more in depth git documentation, see the
  27 resources on the Git community documentation page:
  28
  29         http://git-scm.com/documentation
  30
  31 Pixman uses the infrastructure from the freedesktop.org umbrella
  32 project. For instructions about how to use the git service on
  33 freedesktop.org, see:
  34
  35         http://www.freedesktop.org/wiki/Infrastructure/git/Developers
  36
  37 The Pixman master repository can be found at:
  38
  39         git://anongit.freedesktop.org/git/pixman
  40
  41 and browsed on the web here:
  42
  43         http://cgit.freedesktop.org/pixman/
  44
  45
  46 Sending patches
  47 ---------------
  48
  49 The general workflow for sending patches is to first make sure that
  50 git can send mail on your system. Then,
  51
  52  - create a branch off of master in your local git repository
  53
  54  - make your changes as one or more commits
  55
  56  - use the
  57
  58         git send-email
  59
  60    command to send the patch series to pixman@lists.freedesktop.org.
  61
  62 In order for your patches to be accepted, please consider the
  63 following guidelines:
  64
  65  - This link:
  66
  67         http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#patch-series
  68
  69    describes how what a good patch series is, and to create one with
  70    git.
  71
  72  - At each point in the series, pixman should compile and the test
  73    suite should pass.
  74
  75    The exception here is if you are changing the test suite to
  76    demonstrate a bug. In this case, make one commit that makes the
  77    test suite fail due to the bug, and then another commit that fixes
  78    the bug.
  79
  80    You can run the test suite with
  81
  82         make check
  83
  84    It will take around two minutes to run on a modern PC.
  85
  86  - Follow the coding style described in the CODING_STYLE file
  87
  88  - For bug fixes, include an update to the test suite to make sure
  89    the bug doesn't reappear.
  90
  91  - For new features, add tests of the feature to the test
  92    suite. Also, add a program demonstrating the new feature to the
  93    demos/ directory.
  94
  95  - Write descriptive commit messages. Useful information to include:
  96         - Benchmark results, before and after
  97         - Description of the bug that was fixed
  98         - Detailed rationale for any new API
  99         - Alternative approaches that were rejected (and why they
 100           don't work)
 101         - If review comments were incorporated, a brief version
 102           history describing what those changes were.
 103
 104  - For big patch series, send an introductory email with an overall
 105    description of the patch series, including benchmarks and
 106    motivation. Each commit message should still be descriptive and
 107    include enough information to understand why this particular commit
 108    was necessary.
 109
 110 Pixman has high standards for code quality and so almost everybody
 111 should expect to have the first versions of their patches rejected.
 112
 113 If you think that the reviewers are wrong about something, or that the
 114 guidelines above are wrong, feel free to discuss the issue on the
 115 list. The purpose of the guidelines and code review is to ensure high
 116 code quality; it is not an exercise in compliance.