forked from openslide/openslide
/
CONTRIBUTING.txt
51 lines (39 loc) · 2.19 KB
/
CONTRIBUTING.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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.