BUGS

   1 If you find a bug in cairo we would love to hear about it. We're also
   2 trying to make cairo better, and learning about the bugs that users
   3 encounter is an essential part of that. So we really appreciate the
   4 extra effort users put in to providing high-quality bug reports.
   5
   6 There are two acceptable ways to report cairo bugs, and you can choose
   7 which you prefer:
   8
   9 1) Gitlab bug tracking database:
  10
  11    You can use the following web interface to report new bugs, follow
  12    up on previous bug reports, and search for existing, known
  13    bugs:
  14
  15         https://gitlab.freedesktop.org/cairo/cairo/-/issues
  16
  17    It is necessary to go through a quick account creation process,
  18    (with email address verification), in order to be able to report
  19    new bugs in gitlab. We apologize for any inconvenience that might
  20    cause, and hope it won't prevent you from reporting bugs.
  21
  22 2) Cairo mailing list:
  23
  24    For people who cannot stand the gitlab interface, you can just
  25    send an email to cairo mailing list (cairo@cairographics.org). The
  26    mailing list only allows posting from subscribers, so use the
  27    following page for subscription instructions:
  28
  29         https://cairographics.org/lists
  30
  31    Again, we apologize for any inconvenience this subscription step
  32    might cause, but we've found it necessary to require this in order
  33    to enjoy spam-free discussions on the list.
  34
  35    If you don't actually _want_ to be a subscriber to the mailing
  36    list, but just want to be able to send a message, the easiest thing
  37    to do is to go through the subscription process, and then use the
  38    preferences page to disable message delivery to your address.
  39
  40 Which of the above you use to report bugs depends on your own
  41 preferences. Some people find just typing an email message much easier
  42 than using the web-based forms on gitlab. Others greatly prefer the
  43 ability to check back on a specific bug entry in gitlab without
  44 having to ask on the mailing list if an issue has been resolved.
  45
  46 Regardless of which method you use, here are some general tips that
  47 will help you improve the quality of your bug report, (which will help
  48 in getting the bug fixed sooner):
  49
  50 1) Check to see if the bug has been reported already. It's pretty easy
  51    to run a search or two against the cairo product in the gitlab
  52    database. Another place to look for known bugs is the cairo ROADMAP:
  53
  54         https://cairographics.org/ROADMAP
  55
  56    which shows a planned schedule of releases and which bug fixes are
  57    being planned for each release.
  58
  59 2) Provide an accurate description of the bug with detailed steps for
  60    how we can reproduce the problem.
  61
  62 3) If possible provide a minimal test case demonstrating the bug. A
  63    great test case would be a minimal self-contained function in C or
  64    python or whatever language you are using for cairo. The function
  65    might accept nothing more than a cairo context, (cairo_t* in C).
  66
  67 4) If you feel like being particularly helpful, you could craft this
  68    minimal test case in the form necessary for cairo's test
  69    suite. This isn't much more work than writing a minimal
  70    function. Just look at the cairo/test/README file and imitate the
  71    style of existing test cases.
  72
  73    If you do submit a test case, be sure to include Copyright
  74    information, (with the standard MIT licensing blurb if you want us
  75    to include your test in the test case). Also, including a reference
  76    image showing the expected result will be extremely useful.
  77
  78 5) Finally, the best bug report also comes attached with a patch to
  79    cairo to fix the bug. So send this too if you have it! Otherwise,
  80    don't worry about it and we'll try to fix cairo when we can.
  81
  82 Thanks, and have fun with cairo!
  83
  84 -Carl