Add notes on reporting bugs to BUGS file and move bugs listed there to ROADMAP instead.

2 files changed, 116 insertions, 36 deletions

diff --git a/BUGS b/BUGS
index 959ad3e1d..ef044046d 100644
--- a/BUGS
+++ b/BUGS
@@ -1,56 +1,85 @@
-The place to find a current list of known bugs for cairo is:
+If you find a bug in cairo we would love to hear about it. We're also
+trying to make cairo better, and learning about the bugs that users
+encounter is an essential part of that. So we really appreciate the
+extra effort users put in to providing high-quality bug reports.
 
-	http://bugs.freedesktop.org
+There are two acceptable ways to report cairo bugs, and you can choose
+which you prefer:
+
+1) Bugzilla bug tracking database:
 
-under either the cairo or libpixman products. New bugs should be
-reported there as well.
+   You can use the following web interface to report new bugs, follow
+   up on previous bug reports, and search for existing, known
+   bugs. Just use the "cairo" product:
+
+	http://bugs.freedesktop.org
 
-[A few old bugs have not been moved to bugs.freedesktop.org and are
-instead listed below:]
+   It is necessary to go through a quick account creation process,
+   (with email address verification), in order to be able to report
+   new bugs in bugzilla. We apologize for any inconvenience that might
+   cause, and hope it won't prevent you from reporting bugs.
 
---
+2) Cairo mailing list:
 
-The caches need to be invalidated at font destruction time.
+   For people who cannot stand the bugzilla interface, you can just
+   send an email to cairo mailing list (cairo@cairographics.org). The
+   mailing list only allows posting from subscribers, so use the
+   following page for subscription instructions:
 
---
+	http://cairographics.org/lists
 
-The polygon tessellation routine has problems. It appears that the
-following paper has the right answers:
+   Again, we apologize for any inconvenience this subscription step
+   might cause, but we've found it necessary to require this in order
+   to enjoy spam-free discussions on the list.
 
-	http://cm.bell-labs.com/cm/cs/doc/93/2-27.ps.gz
+   If you don't actually _want_ to be a subscriber to the mailing
+   list, but just want to be able to send a message, the easiest thing
+   to do is to go through the subscription process, and then use the
+   preferences page to disable message delivery to your address.
 
-	[Hobby93c] John D. Hobby, Practical Segment Intersection with
-	Finite Precision Output, Computation Geometry Theory and
-	Applications, 13(4), 1999.
+Which of the above you use to report bugs depends on your own
+preferences. Some people find just typing an email message much easier
+than using the web-based forms on bugzilla. Others greatly prefer the
+ability to check back on a specific bug entry in bugzilla without
+having to ask on the mailing list if an issue has been resolved.
 
-Recent improvements to make the intersection code more robust (using
-128-bit arithmetic where needed), have exposed some of the weakness in
-the current tessellation implementation. So, for now, filling some
-polygons will cause "leaking" until we implement Hobby's algorithm.
+Regardless of which method you use, here are some general tips that
+will help you improve the quality of your bug report, (which will help
+in getting the bug fixed sooner):
 
---
+1) Check to see if the bug has been reported already. It's pretty easy
+   to run a search or two against the cairo product in the
+   http://bugs.freedesktop.org bugzilla database. Another place to
+   look for known bugs is the cairo ROADMAP:
 
-Stroke extents might not work for degenerate cases, (e.g. single
-vertical or horizontal line).
+	http://cairographics.org/ROADMAP
 
---
+   which shows a planned schedule of releases and which bug fixes are
+   being planned for each release.
 
-Stroke width of 0 might do bad things.
+2) Provide an accurate description of the bug with detailed steps for
+   how we can reproduce the problem.
 
---
+3) If possible provide a minimal test case demonstrating the bug. A
+   great test case would be a minimal self-contained function in C or
+   python or whatever language you are using for cairo. The function
+   might accept nothing more than a cairo context, (cairo_t* in C).
 
-Could there be a bug in PS backend exposed by?:
+4) If you feel like being particularly helpful, you could craft this
+   minimal test case in the form necessary for cairo's test
+   suite. This isn't much more work than writing a minimal
+   function. Just look at the cairo/test/README file and imitate the
+   style of existing test cases.
 
-cairo_save
-cairo_clip
-cairo_restore
-...
+   If you do submit a test case, be sure to include Copyright
+   information, (with the standard MIT licensing blurb if you want us
+   to include your test in the test case). Also, including a reference
+   image showing the expected result will be extremely useful.
 
-This needs a new testcase.
+5) Finally, the best bug report also comes attached with a patch to
+   cairo to fix the bug. So send this too if you have it! Otherwise,
+   don't worry about it and we'll try to fix cairo when we can.
 
---
+Thanks, and have fun with cairo!
 
-Text drawn with vertical metrics cannot currently use TrueType
-subsetting for PDF/PS output as the code doesn't write out the necessary
-VHEA or VMTX entries to the TrueType font objects. As a result, cairo uses
-Type3 fonts which generates slightly different outlines.
+-Carl
diff --git a/ROADMAP b/ROADMAP
index 5294cadfc..ade107650 100644
--- a/ROADMAP
+++ b/ROADMAP
@@ -136,3 +136,54 @@ Unscheduled stuff we'd like to get to at some point
  Misc
      1. xlib backend requires xrender to compile, while it can perform without
         xrender at run time.  Make it compile without it.
+
+[Here's some stuff that was sitting in the BUGS file. Some of these
+are likely not existing bugs anymore. We should invesitgate each and
+either move it up into the ROADMAP above or else just delete it.]
+
+--
+
+The caches need to be invalidated at font destruction time.
+
+--
+
+The polygon tessellation routine has problems. It appears that the
+following paper has the right answers:
+
+	http://cm.bell-labs.com/cm/cs/doc/93/2-27.ps.gz
+
+	[Hobby93c] John D. Hobby, Practical Segment Intersection with
+	Finite Precision Output, Computation Geometry Theory and
+	Applications, 13(4), 1999.
+
+Recent improvements to make the intersection code more robust (using
+128-bit arithmetic where needed), have exposed some of the weakness in
+the current tessellation implementation. So, for now, filling some
+polygons will cause "leaking" until we implement Hobby's algorithm.
+
+--
+
+Stroke extents might not work for degenerate cases, (e.g. single
+vertical or horizontal line).
+
+--
+
+Stroke width of 0 might do bad things.
+
+--
+
+Could there be a bug in PS backend exposed by?:
+
+cairo_save
+cairo_clip
+cairo_restore
+...
+
+This needs a new testcase.
+
+--
+
+Text drawn with vertical metrics cannot currently use TrueType
+subsetting for PDF/PS output as the code doesn't write out the necessary
+VHEA or VMTX entries to the TrueType font objects. As a result, cairo uses
+Type3 fonts which generates slightly different outlines.