Create CONTRIBUTING.md and update README.md

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+If your contribution is not straightforward, consider first creating an
+issue to discuss the change as this can save you time by getting the advice of
+the maintainers.
+
+If you're working on an issue it's a good idea to add a comment to that
+issue to tell others and reduce the chance that two people work on the same thing
+at the same time.
+
+## Testing
+
+Testing this crate requires the `nightly` toolchain due to using the unstable
+`test` feature for benchmarks:
+
+```sh
+cargo +nightly test
+```
+
+## Reporting issues
+
+Before reporting an issue on the [issue
+tracker](https://github.com/rust-github/template/issues), please check that it
+has not already been reported by searching for some related keywords.
+
+Minimal reproducible examples are appreciated for bug reports.
+
+## Documentation
+
+This crate uses `katexit` to render equations in documentation.
+To open the documentation locally with `katexit` enabled, run:
+
+```sh
+cargo doc --open --features=katexit
+```
+
+## Help wanted
+
+All pull requests are welcome. Some specific areas that would be great to
+get some help with are:
+
+- Performance - profiling current code, documenting or fixing performance
+  problems, adding benchmarks, comparisons to other libraries
+- Testing - more unit tests and regression tests. Some more property-based
+  testing would be particularly nice
+- Documentation - particularly more example code showing what's currently
+  possible

README.md

@@ -1,57 +1,64 @@
-imageproc
-====
+# imageproc
 
 [![crates.io](https://img.shields.io/crates/v/imageproc.svg)](https://crates.io/crates/imageproc)
 [![doc-badge]][doc-link]
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/image-rs/imageproc/blob/master/LICENSE)
 [![Dependency status](https://deps.rs/repo/github/image-rs/imageproc/status.svg)](https://deps.rs/repo/github/image-rs/imageproc)
 
-An image processing library, based on the [image](https://github.com/image-rs/image) library. There may initially
-be overlap between the functions in this library and those in `image::imageops`.
-
-This is very much a work in progress. If you have ideas for things that could be done better, or new features you'd like to see, then please create issues for them. Nothing's set in stone.
+An image processing library, based on the
+[`image`](https://github.com/image-rs/image) library.
 
 [API documentation][doc-link]
 
 [doc-badge]: https://docs.rs/imageproc/badge.svg
 [doc-link]: https://docs.rs/imageproc
 
-# Goals
+## Goals
 
-A performant, well-tested, well-documented library with a consistent API, suitable for use as the basis of computer vision applications or graphics editors.
+A performant, well-tested, well-documented library with a consistent API, suitable for use as
+the basis of computer vision applications or graphics editors.
 
-# Non-goals
+## Non-goals
 
 Maximum genericity over image storages or formats, or support for higher-dimensional images.
 
-Full blown computer vision applications (e.g. face recognition or image registration) probably also belong elsewhere, but the line's a bit blurred here (e.g. is image in-painting an image processing task or a computer vision task?). However, worrying about how to structure the code can probably wait until we have more code to structure...
+## Color Space
+
+Functions in this library implicitly assume that pixels colors are
+stored in a linear color space like `RGB` as opposed to a non-linear color
+space such as `sRGB`.
+
+If you are not familiar with gamma correction then [this article] contains
+an introduction and examples of color artefacts resulting
+from not using linear color spaces.
+
+[this article]: https://blog.johnnovak.net/2016/09/21/what-every-coder-should-know-about-gamma/
 
-# Crate Features
+## Parallelism
 
-Imageproc is built with these features enabled by default:
+This library provides both single-threaded and multi-threaded variations of several functions
+by using [rayon](https://github.com/rayon-rs/rayon).
 
--   `rayon` enables multithreading for certain operations (e.g., geometric transformations) via [rayon](https://github.com/rayon-rs/rayon)
+Depending on image size and the amount of work performed per pixel the parallel versions may not 
+always be faster - we recommend benchmarking for your specific use-case.
 
-Optionally, the following dependencies can be enabled:
+## Crate Features
 
--   `property-testing` exposes helper types and methods to enable property testing via [quickcheck](https://github.com/BurntSushi/quickcheck)
--   `display-window` enables the displaying of images (using `imageproc::window`) with [sdl2](https://github.com/Rust-SDL2/rust-sdl2)
+### Default Features
 
-# How to contribute
+- `rayon`: enables multi-threaded versions of several functions
 
-All pull requests are welcome. Some specific areas that would be great to get some help with are:
+### Optional Features
 
-* New features! If you're planning on adding some new functions or modules, please create an issue with a name along the lines of "Add [feature name]" and assign it to yourself (or comment on the issue that you're planning on doing it). This way we'll not have multiple people working on the same functionality.
-* Performance - profiling current code, documenting or fixing performance problems, adding benchmarks, comparisons to other libraries.
-* Testing - more unit tests and regression tests. Some more property-based testing would be particularly nice.
-* APIs - are the current APIs hard to use or inconsistent? Some open questions: Should we return Result types more often? How should functions indicate acceptable input image dimensions? Should we use enum arguments or have lots of similarly named functions? What's the best way to get concise code while still allowing control over allocations?
-* Documentation - particularly more example code showing what's currently possible. Pretty pictures in this README.
-* Feature requests - are there any functions you'd like to see added? Is the library currently unsuitable for your use case for some reason?
+- `katexit`: enables latex in documentation via
+  [katexit](https://github.com/termoshtt/katexit)
+- `property-testing`: enables `quickcheck`
+- `quickcheck`: exposes helper types and methods to enable property testing
+  via [quickcheck](https://github.com/BurntSushi/quickcheck)
+- `display-window`: enables `sdl2`
+- `sdl2`: enables the displaying of images (using `imageproc::window`) with
+  [sdl2](https://github.com/Rust-SDL2/rust-sdl2)
 
-## Documentation
+## How to contribute
 
-This crate uses `katexit` to render equations in the documentation.
-To open the documentation locally with `katexit` enabled, use
-```sh
-cargo doc --open --features=katexit
-```
+See [`CONTRIBUTING.md`].