Improve README, add CONTRIBUTING

Rewrite the README.md with an example.
Add a file CONTRIBUTING.md that describes
how to make release.

.gitignore

@@ -4,3 +4,4 @@ Cargo.lock
 tokamak.toml
 .idea
 *.iml
+examples/ferris.cbor

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing to Serde CBOR
+Thanks for your interest!
+There are many ways to help:
+
+* write an issue about a problem you encountered
+* submit a pull request
+* add documentation and examples
+
+## Pull Requests
+
+Code should be easy to understand and documented.
+For new features and fixed bugs please add a test to one of the files in `test/`.
+The tests are run on Travis CI to catch regressions early.
+Format your code with `cargo fmt` before committing.
+Currently Serde CBOR does not contain `unsafe` code and I would like to keep it this way.
+
+## Making a Release
+
+* [ ] Make sure the crate compiles and all tests pass.
+* [ ] (Optional) Test that the fuzzer works and fuzz the crate for some time.
+* [ ] Write a list with all changes made since the last release
+* [ ] Increment the version number in `Cargo.toml` and the `README.md`. Bugfixes increase the patch version while new features or an increased minimum Rust version require a new minor version.
+* [ ] Check that the file `examples/readme.rs` and the example from the `README.md` match.
+* [ ] Commit the changes.
+* [ ] Add a git tag with the new version number:
+    `git tag "v42.0.2"`
+* [ ] Push the changes: `git push --tags`
+* [ ] Run `cargo publish`
+* [ ] Add a new release to GitHub with a list of changes.

Cargo.toml

@@ -5,14 +5,17 @@ authors = [
     "Pyfisch <[email protected]>",
     "Steven Fackler <[email protected]>"]
 repository = "https://github.com/pyfisch/cbor"
-documentation = "https://docs.rs/serde_cbor/"
 readme = "README.md"
 license = "MIT/Apache-2.0"
 description = "CBOR support for serde."
 keywords = ["serde", "cbor", "serialization"]
 categories = ["encoding"]
 edition = "2018"
 
+[badges]
+travis-ci = { repository = "pyfisch/cbor" }
+maintenance = { status = "actively-developed" }
+
 [dependencies]
 byteorder = "1.0.0"
 half = "1.2.0"

README.md

@@ -1,19 +1,69 @@
-# Serde CBOR Serialization Library
+# Serde CBOR
 [![Build Status](https://travis-ci.org/pyfisch/cbor.svg?branch=master)](https://travis-ci.org/pyfisch/cbor)
 [![Crates.io](https://img.shields.io/crates/v/serde_cbor.svg)](https://crates.io/crates/serde_cbor)
-[Documentation](https://pyfisch.github.io/cbor/serde_cbor/)
-
-This crate is a Rust library for parsing and generating the
-[CBOR](http://cbor.io/) (Concise Binary Object Representation)
-file format. It is built upon [Serde](https://github.com/serde-rs/serde),
-a high performance generic serialization framework.
-
-## About CBOR
-CBOR is a binary encoding based on a superset of the JSON data model.
-It supports all the standard JSON types plus binary data, big numbers,
-non-string keys, time values and custom data types using tagging of values.
-CBOR is always shorter than the corresponding JSON representation and easier
-and faster to parse.
+[![Documentation](https://docs.rs/serde_cbor/badge.svg)](https://docs.rs/serde_cbor)
+
+This crate implements the Concise Binary Object Representation from [RFC 7049].
+It builds on [Serde] the generic serialization  framework for Rust.
+CBOR provides a binary encoding for a superset
+of the JSON data model that is small and very fast to parse.
+
+[RFC 7049]: https://tools.ietf.org/html/rfc7049
+[Serde]: https://github.com/serde-rs/serde
+
+## Usage
+
+Serde CBOR supports Rust 1.31 and up. Add this to your `Cargo.toml`:
+```toml
+[dependencies]
+serde_cbor = "0.9"
+```
+
+Storing and loading Rust types is easy and requires only
+minimal modifications to the program code.
+
+```rust
+use std::error::Error;
+use std::fs::File;
+use serde_derive::{Deserialize, Serialize};
+
+// Types annotated with `Serialize` can be stored as CBOR.
+// To be able to load them again add `Deserialize`.
+#[derive(Debug, Serialize, Deserialize)]
+struct Mascot {
+    name: String,
+    species: String,
+    year_of_birth: u32,
+}
+
+fn main() -> Result<(), Box<Error>> {
+    let ferris = Mascot {
+        name: "Ferris".to_owned(),
+        species: "crab".to_owned(),
+        year_of_birth: 2015,
+    };
+
+    let mut ferris_file = File::create("examples/ferris.cbor")?;
+    // Write Ferris to the given file.
+    // Instead of a file you can use any type that implements `io::Write`
+    // like a HTTP body, database connection etc.
+    serde_cbor::to_writer(&mut ferris_file, &ferris)?;
+
+    let mut tux_file = File::open("examples/tux.cbor")?;
+    // Load Tux from a file.
+    // Serde CBOR performs roundtrip serialization meaning that
+    // the data will not change in any way.
+    let tux: Mascot = serde_cbor::from_reader(&mut tux_file)?;
+
+    println!("{:?}", tux);
+    // prints: Mascot { name: "Tux", species: "penguin", year_of_birth: 1996 }
+
+    Ok(())
+}
+```
+
+There are a lot of options available to customize the format.
+To operate on untyped CBOR values have a look at the `Value` type.
 
 ## License
 Licensed under either of

examples/readme.rs

@@ -0,0 +1,39 @@
+// NOTE: This file should be kept in sync with README.md
+
+use std::error::Error;
+use std::fs::File;
+use serde_derive::{Deserialize, Serialize};
+
+// Types annotated with `Serialize` can be stored as CBOR.
+// To be able to load them again add `Deserialize`.
+#[derive(Debug, Serialize, Deserialize)]
+struct Mascot {
+    name: String,
+    species: String,
+    year_of_birth: u32,
+}
+
+fn main() -> Result<(), Box<Error>> {
+    let ferris = Mascot {
+        name: "Ferris".to_owned(),
+        species: "crab".to_owned(),
+        year_of_birth: 2015,
+    };
+
+    let mut ferris_file = File::create("examples/ferris.cbor")?;
+    // Write Ferris to the given file.
+    // Instead of a file you can use any type that implements `io::Write`
+    // like a HTTP body, database connection etc.
+    serde_cbor::to_writer(&mut ferris_file, &ferris)?;
+
+    let mut tux_file = File::open("examples/tux.cbor")?;
+    // Load Tux from a file.
+    // Serde CBOR performs roundtrip serialization meaning that
+    // the data will not change in any way.
+    let tux: Mascot = serde_cbor::from_reader(&mut tux_file)?;
+
+    println!("{:?}", tux);
+    // prints: Mascot { name: "Tux", species: "penguin", year_of_birth: 1996 }
+
+    Ok(())
+}

examples/tux.cbor

@@ -0,0 +1 @@
+�dnamecTuxgspeciesgpenguinmyear_of_birth�