Home | History | Annotate | Line # | Download | only in dist
README revision 1.1.1.6 
      1 Pixman
      2 ======
      3 
      4 Pixman is a library that provides low-level pixel manipulation
      5 features such as image compositing and trapezoid rasterization.
      6 
      7 Questions should be directed to the pixman mailing list:
      8 
      9     https://lists.freedesktop.org/mailman/listinfo/pixman
     10 
     11 You can also file bugs at
     12 
     13     https://gitlab.freedesktop.org/pixman/pixman/-/issues/new
     14 
     15 or submit improvements in form of a Merge Request via
     16 
     17     https://gitlab.freedesktop.org/pixman/pixman/-/merge_requests
     18 
     19 For real time discussions about pixman, feel free to join the IRC
     20 channels #cairo and #xorg-devel on the FreeNode IRC network.
     21 
     22 
     23 Contributing
     24 ------------
     25 
     26 In order to contribute to pixman, you will need a working knowledge of
     27 the git version control system. For a quick getting started guide,
     28 there is the "Everyday Git With 20 Commands Or So guide"
     29 
     30     https://www.kernel.org/pub/software/scm/git/docs/everyday.html
     31 
     32 from the Git homepage. For more in depth git documentation, see the
     33 resources on the Git community documentation page:
     34 
     35     https://git-scm.com/documentation
     36 
     37 Pixman uses the infrastructure from the freedesktop.org umbrella
     38 project. For instructions about how to use the git service on
     39 freedesktop.org, see:
     40 
     41     https://www.freedesktop.org/wiki/Infrastructure/git/Developers
     42 
     43 The Pixman master repository can be found at:
     44 
     45     https://gitlab.freedesktop.org/pixman/pixman
     46 
     47 
     48 Sending patches
     49 ---------------
     50 
     51 Patches should be submitted in form of Merge Requests via Gitlab.
     52 
     53 You will first need to create a fork of the main pixman repository at
     54 
     55     https://gitlab.freedesktop.org/pixman/pixman
     56 
     57 via the Fork button on the top right. Once that is done you can add your
     58 personal repository as a remote to your local pixman development git checkout:
     59 
     60     git remote add my-gitlab git (a] gitlab.freedesktop.org:YOURUSERNAME/pixman.git
     61 
     62     git fetch my-gitlab
     63 
     64 Make sure to have added ssh keys to your gitlab profile at
     65 
     66     https://gitlab.freedesktop.org/profile/keys
     67 
     68 Once that is set up, the general workflow for sending patches is to create a
     69 new local branch with your improvements and once it's ready push it to your
     70 personal pixman fork:
     71 
     72     git checkout -b fix-some-bug
     73     ...
     74     git push my-gitlab
     75 
     76 The output of the `git push` command will include a link that allows you to
     77 create a Merge Request against the official pixman repository.
     78 
     79 Whenever you make changes to your branch (add new commits or fix up commits)
     80 you push them back to your personal pixman fork:
     81 
     82     git push -f my-gitlab
     83 
     84 If there is an open Merge Request Gitlab will automatically pick up the
     85 changes from your branch and pixman developers can review them anew.
     86 
     87 In order for your patches to be accepted, please consider the
     88 following guidelines:
     89 
     90  - At each point in the series, pixman should compile and the test
     91    suite should pass.
     92 
     93    The exception here is if you are changing the test suite to
     94    demonstrate a bug. In this case, make one commit that makes the
     95    test suite fail due to the bug, and then another commit that fixes
     96    the bug.
     97 
     98    You can run the test suite with 
     99 
    100         make check
    101 
    102    if you built pixman with autotools or
    103 
    104        meson test -C builddir
    105 
    106    if you built pixman with meson.
    107 
    108    It will take around two minutes to run on a modern PC.
    109 
    110  - Follow the coding style described in the CODING_STYLE file
    111 
    112  - For bug fixes, include an update to the test suite to make sure
    113    the bug doesn't reappear.
    114 
    115  - For new features, add tests of the feature to the test
    116    suite. Also, add a program demonstrating the new feature to the
    117    demos/ directory.
    118 
    119  - Write descriptive commit messages. Useful information to include:
    120         - Benchmark results, before and after
    121 	- Description of the bug that was fixed
    122 	- Detailed rationale for any new API
    123 	- Alternative approaches that were rejected (and why they
    124           don't work)
    125 	- If review comments were incorporated, a brief version
    126           history describing what those changes were.
    127 
    128  - For big patch series, write an introductory post with an overall
    129    description of the patch series, including benchmarks and
    130    motivation. Each commit message should still be descriptive and
    131    include enough information to understand why this particular commit
    132    was necessary.
    133 
    134 Pixman has high standards for code quality and so almost everybody
    135 should expect to have the first versions of their patches rejected.
    136 
    137 If you think that the reviewers are wrong about something, or that the
    138 guidelines above are wrong, feel free to discuss the issue. The purpose
    139 of the guidelines and code review is to ensure high code quality; it is
    140 not an exercise in compliance.
    141