README (4510B)
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@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 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 128 Pixman has high standards for code quality and so almost everybody 129 should expect to have the first versions of their patches rejected. 130 131 If you think that the reviewers are wrong about something, or that the 132 guidelines above are wrong, feel free to discuss the issue. The purpose 133 of the guidelines and code review is to ensure high code quality; it is 134 not an exercise in compliance.