Add a code of conduct and a contributing guide

* Add a guide for contributing to this crate

* Add code of conduct notice

* Update README with links, also fixes #176

contributing.md

@@ -0,0 +1,67 @@
+# Contributing to `packed_simd`
+
+Welcome! If you are reading this document, it means you are interested in contributing
+to the `packed_simd` crate.
+
+## Reporting issues
+
+All issues with this crate are tracked using GitHub's [Issue Tracker].
+
+You can use issues to bring bugs to the attention of the maintainers, to discuss
+certain problems encountered with the crate, or to request new features (although
+feature requests should be limited to things mentioned in the [RFC]).
+
+One thing to keep in mind is to always use the **latest** nightly toolchain when
+working on this crate. Due to the nature of this project, we use a lot of unstable
+features, meaning breakage happens often.
+
+[Issue Tracker]: https://github.com/rust-lang-nursery/packed_simd/issues
+[RFC]: https://github.com/rust-lang/rfcs/pull/2366
+
+### LLVM issues
+
+The Rust compiler relies on [LLVM](https://llvm.org/) for machine code generation,
+and quite a few LLVM bugs have been discovered during the development of this project.
+
+If you encounter issues with incorrect/suboptimal codegen, which you do not encounter
+when using the [SIMD vendor intrinsics](https://doc.rust-lang.org/nightly/std/arch/),
+it is likely the issue is with LLVM, or this crate's interaction with it.
+
+You should first open an issue **in this repo** to help us track the problem, and we
+will help determine what is the exact cause of the problem.
+If LLVM is indeed the cause, the issue will be reported upstream to the
+[LLVM bugtracker](https://bugs.llvm.org/).
+
+## Submitting Pull Requests
+
+New code is submitted to the crate using GitHub's [pull request] mechanism.
+You should first fork this repository, make your changes (preferrably in a new
+branch), then use GitHub's web UI to create a new PR.
+
+[pull request]: https://help.github.com/articles/about-pull-requests/
+
+### Examples
+
+The `examples` directory contains code showcasing SIMD code written with this crate,
+usually in comparison to scalar or ISPC code. If you have a project / idea which
+uses SIMD, we'd love to add it to the examples list.
+
+Every example should include a small `README`, describing the example code's purpose.
+If your example could potentially work as a benchmark, then add a `benchmark.sh`
+script to allow running the example benchmark code in CI. See an existing example's
+[`benchmark.sh`](examples/aobench/benchmark.sh) for a sample.
+
+Don't forget to update the crate's top-level `README` with a link to your example.
+
+### Perf guide
+
+The objective of the [performance guide][perf-guide] is to be a comprehensive
+resource detailing the process of optimizing Rust code with SIMD support.
+
+If you believe a certain section could be reworded, or if you have any tips & tricks
+related to SIMD which you'd like to share, please open a PR.
+
+[mdBook] is used to manage the formatting of the guide as a book.
+
+[perf-guide]: https://rust-lang-nursery.github.io/packed_simd/perf-guide/
+[mdBook]: https://github.com/rust-lang-nursery/mdBook

readme.md

@@ -1,12 +1,14 @@
-# `Simd<[T; N]>` - Implementation of [RFC2366: `std::simd`][rfc2366]
+# `Simd<[T; N]>`
+
+## Implementation of [Rust RFC #2366: `std::simd`][rfc2366]
 
 [![Travis-CI Status]][travis] [![Appveyor Status]][appveyor] [![Latest Version]][crates.io] [![docs]][master_docs]
 
-> This aims to be a 100% conforming implementation of the RFC2366 for stabilization.
+> This aims to be a 100% conforming implementation of Rust RFC 2366 for stabilization.
 
 **WARNING**: this crate only supports the most recent nightly Rust toolchain.
 
-# Documentation
+## Documentation
 
 * [API docs (`master` branch)][master_docs]
 * [Performance guide][perf_guide]
@@ -15,7 +17,7 @@
 * [RFC2366 `std::simd`][rfc2366]: - contains motivation, design rationale,
   discussion, etc.
 
-# Examples
+## Examples
 
 Most of the examples come with both a scalar and a vectorized implementation.
 
@@ -26,28 +28,29 @@ Most of the examples come with both a scalar and a vectorized implementation.
 * [`n-body`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/nbody)
 * [`options_pricing`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/options_pricing)
 * [`spectral_norm`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/spectral_norm)
+* [`triangle transform`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/triangle_xform)
 * [`stencil`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/stencil)
 * [`vector dot product`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/dot_product)
 
-# Cargo features
+## Cargo features
 
 * `into_bits` (default: disabled): enables `FromBits`/`IntoBits` trait
   implementations for the vector types. These allow reinterpreting the bits of a
   vector type as those of another vector type safely by just using the
   `.into_bits()` method.
-  
+
 * `coresimd` (default: disabled): enable this feature to recompile `core::arch`
   for the target-features enabled. `packed_simd` includes optimizations for some
-  target feature combinations that are enabled by this feature. Note, however, 
+  target feature combinations that are enabled by this feature. Note, however,
   that this is an unstable dependency, that rustc might break at any time.
-  
+
 * `sleef-sys` (default: disabled - `x86_64` only): internally uses the [SLEEF]
   short-vector math library when profitable via the [`sleef-sys`][sleef_sys]
   crate. [SLEEF] is licensed under the [Boost Software License
   v1.0][boost_license], an extremely permissive license, and can be statically
   linked without issues.
 
-# Performance
+## Performance
 
 The following [ISPC] examples are also part of `packed_simd`'s
 [`examples/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/examples/)
@@ -61,16 +64,16 @@ slowdown:
 * `stencil`: `[+1.06x, +1.72x]`,
 * `mandelbrot`: `[-1.74x, +1.2x]`,
 * `options_pricing`:
-   * `black_scholes`: `+1.0x` 
-   * `binomial_put`: `+1.4x` 
+   * `black_scholes`: `+1.0x`
+   * `binomial_put`: `+1.4x`
 
  While SPMD is not the intended use case for `packed_simd`, it is possible to
  combine the library with [`rayon`][rayon] to poorly emulate [ISPC]'s SPMD programming
  model in Rust. Writing performant code is not as straightforward as with
  [ISPC], but with some care (e.g. see the [Performance Guide][perf_guide]) one
  can easily match and often out-perform [ISPC]'s "default performance".
 
-# Platform support
+## Platform support
 
 The following table describes the supported platforms: `build` shows whether the
 library compiles without issues for a given target, while `run` shows whether
@@ -125,27 +128,33 @@ there are correctness bugs open in the issue tracker.
 
 [**] it is currently not easily possible to run these platforms on CI.
 
-
-# Machine code verification
+## Machine code verification
 
 The
 [`verify/`](https://github.com/rust-lang-nursery/packed_simd/tree/master/verify)
 crate tests disassembles the portable packed vector APIs at run-time and
 compares the generated machine code against the desired one to make sure that
 this crate remains efficient.
 
-# License
+## License
 
 This project is licensed under either of
 
- * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
-   http://www.apache.org/licenses/LICENSE-2.0)
- * MIT license ([LICENSE-MIT](LICENSE-MIT) or
-   http://opensource.org/licenses/MIT)
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+  ([LICENSE-APACHE](LICENSE-APACHE))
+
+* [MIT License](http://opensource.org/licenses/MIT)
+  ([LICENSE-MIT](LICENSE-MIT))
 
 at your option.
 
-### Contribution
+## Contributing
+
+We welcome all people who want to contribute.
+Please see the [contributing instructions] for more information.
+
+Contributions in any form (issues, pull requests, etc.) to this project
+must adhere to Rust's [Code of Conduct].
 
 Unless you explicitly state otherwise, any contribution intentionally submitted
 for inclusion in `packed_simd` by you, as defined in the Apache-2.0 license, shall be
@@ -167,3 +176,5 @@ dual licensed as above, without any additional terms or conditions.
 [boost_license]: https://www.boost.org/LICENSE_1_0.txt
 [SLEEF]: https://sleef.org/
 [sleef_sys]: https://crates.io/crates/sleef-sys
+[contributing instructions]: contributing.md
+[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html