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