1Contributing to libjpeg-turbo 2============================= 3 4libjpeg-turbo is a stable and mature product with a worldwide reach, it is an 5ISO/ITU-T reference implementation of the JPEG standard, and its maintainer 6does not earn a salary for maintaining it. Thus, not every code contribution 7can or will be accepted into the libjpeg-turbo code base. In order to maximize 8the chances that a code contribution is acceptable, please adhere to the 9following guidelines: 10 111. If the code contribution is a bug fix, then please ensure that enough 12information is provided so that the maintainer can readily reproduce and 13document the bug. That information should include: 14 - A clear and concise description of the bug 15 - The steps and (if applicable) images necessary to reproduce the bug 16 - The compilers, operating systems, and CPUs with which the bug was 17 observed 18 - The versions of libjpeg-turbo with which the bug was observed 19 - If the bug is a regression, the specific commit that introduced the bug 20 (use `git bisect` to determine this) 21 222. If the code contribution will implement a major new feature, then please 23contact the project maintainer (through a 24[GitHub issue](https://github.com/libjpeg-turbo/libjpeg-turbo/issues/new), 25[direct e-mail](https://libjpeg-turbo.org/About/Contact), or the 26[libjpeg-turbo-devel mailing list](https://libjpeg-turbo.org/About/MailingLists)) 27prior to implementing the feature. In general, major new features that are 28potentially disruptive to the quality of libjpeg-turbo are unlikely to be 29accepted unless: 30 - The new feature is within the existing scope of libjpeg-turbo. 31 - The new feature has been thoroughly regression tested and benchmarked on 32 all of the supported platforms that are potentially affected by it. 33 - The new feature has been documented clearly and concisely in the change 34 log and (if applicable) the libjpeg and TurboJPEG API documentation and 35 man pages. 36 - The code implementing the new feature is formatted consistently with the 37 rest of the libjpeg-turbo code base (use 38 [checkstyle](https://github.com/libjpeg-turbo/checkstyle) to validate 39 this.) 40 - The new feature does not introduce new members into the exposed libjpeg 41 API structures (doing so would break backward ABI compatibility.) 42 - The new feature does not alter existing libjpeg-turbo usage or 43 development workflows. 44 - The code implementing the new feature is elegant, easily maintainable, 45 and causes the least possible amount of disruption to the libjpeg-turbo 46 code base. 47 - The new feature is based on the dev branch of the libjpeg-turbo 48 repository. 49 50 ... OR ... 51 52 - Your organization is prepared to pay for the labor necessary to ensure 53 all of the above. Even the most well-written patches can still require 54 a significant amount of labor to clean up, test, and integrate. (See 55 above RE: the maintainer not earning a salary.) 56 57 Specific types of features that *will not* be accepted: 58 59 - Features that extend the scope of libjpeg-turbo to support image formats 60 other than DCT-based JPEG and JFIF 61 - Features that extend the scope of libjpeg-turbo to support image 62 processing algorithms that are not necessary for JPEG compression or 63 decompression 64 - Extensions to the JPEG format that have not been approved by the 65 appropriate standards bodies 66 - Non-trivial performance enhancements that have less than a 5% overall 67 impact on performance 68 693. If the code contribution is a build system enhancement, then please be 70prepared to justify the enhancement. In general, build system enhancements 71are unlikely to be accepted unless: 72 - The enhancement is potentially beneficial to a significant number of 73 upstream libjpeg-turbo users/developers. (If the enhancement is only 74 beneficial to a downstream project, then it does not belong here.) 75 - The enhancement has been tested with the following CMake versions: 76 - The earliest version of CMake that libjpeg-turbo currently supports 77 (refer to CMakeLists.txt) 78 - The most recent major version of CMake 79 - (if applicable) The earliest version of CMake with which the 80 enhancement can be used 81 - The enhancement has been tested on all of the major platforms (Mac, 82 Linux, Windows/Visual C++, Windows/MinGW) that are potentially affected 83 by it. 84 - The enhancement does not introduce new build system requirements or CMake 85 variables unless absolutely necessary. 86 - The enhancement does not alter existing libjpeg-turbo development 87 workflows. 88 89 Specific types of build system enhancements that *will not* be accepted: 90 91 - Enhancements that allow libjpeg-turbo to be built from a subdirectory 92 of a downstream repository. These enhancements are not maintainable in 93 the upstream libjpeg-turbo build system. Use the CMake 94 `ExternalProject_Add()` function instead. 95 - Enhancements that introduce new (non-CMake-based) build systems 96