Contributing to OpenSlide
=========================

Adam Goode, June 2010



This document is for any contributors to OpenSlide, including those in
the original OpenSlide group at CMU. It includes some guidelines and
advice.

 * Please do not add new API calls without careful thought. Absolutely
   don't add API as unimplemented stubs "just in case". OpenSlide so
   far has been backward compatible in terms of ABI, and part of this
   comes from carefully adding new API only as needed. Removing a bad
   API will come at the cost of binary compatibility.

   I was able to effectively remove the prefetch API without breaking
   ABI by making it a compile time error to link against it, but this
   was only because the API calls were stubs and never implemented and
   never used. Having these unimplemented stubs was a bad idea because
   while the code was unimplemented, no user could possibly test the
   performance implications of using the prefetch; and if we ever
   actually implemented something it would likely hurt performance of
   any user who might have sprinkled prefetch statements around and
   noticed no performance issues with it.

 * Make sure things build on Windows, at least with MinGW. Many users
   of OpenSlide are on Windows. Testing builds with MSVC would be
   great, but not as critical, since actual users can send patches for
   that. Keep in mind the differences between ELF and COFF shared
   libraries, they can get you. This is especially important when an
   OpenSlide API might consume or return a structure from a DLL that
   OpenSlide links to, in general this is unsafe on Windows.

 * When making a release, try to carefully follow the libtool
   and automake versioning rules. Don't forget the cmake stuff as well
   (not as critical yet, since it's only used for MSVC). Also add a
   changelog entry, update the website, and post to the announce
   mailing list.

 * Try to follow the coding style of nearby code.

 * Maintain thread safety. The openslide_t struct is mostly immutable,
   except for the cache (which takes locks) and libtiff (which is sort
   of a disaster).

 * Avoid the midlayer mistake. The tilehelper and cache are there for
   you.

 * Have fun! Graphics are a joy.
