3 files changed, 36 insertions(+), 15 deletions(-)

M README.md
A benches/README.md
M src/lib.rs

@@ 1,25 1,28 @@
 # serde_bare
 
-An implementation of the BARE (https://baremessages.org) encoding format draft.
-
 [![builds.sr.ht status](https://builds.sr.ht/~tdeo/serde_bare.svg)](https://builds.sr.ht/~tdeo/serde_bare?)
 
-Mailing list: https://lists.sr.ht/~tdeo/serde_bare
-Ticket tracker: https://todo.sr.ht/~tdeo/serde_bare
+An implementation of the [BARE](https://baremessages.org) encoding format draft for Rust using [Serde](https://serde.rs).
+
+BARE is a simple and easy to implement non-self-describing binary serialization format.  
+It has similarities with [Bincode](https://github.com/bincode-org/bincode), but BARE is designed to be usable from programming languages other than Rust.
+
+## Links
+
+Mailing list: https://lists.sr.ht/~tdeo/serde_bare  
+Ticket tracker: https://todo.sr.ht/~tdeo/serde_bare  
+
+## Stability
 
-To run benchmarks on your system:
+Before version 1.0.0, minor version bumps (such as 0.1.0 to 0.2.0) may include changes to how data is serialized and deserialized.
+This may be due to changes in the BARE specification draft, or changes in the mapping between Serde's data model and BARE's.
 
-```sh
-cd benches
-make bench
-```
+After version 1.0.0, updates within a major version (such as 1.0.0 to 1.1.0) will not change how data is serialized and deserialized.
+Major version bumps (such as 1.0.0 to 2.0.0) may change the way data is serialized and deserialized.
 
-Or to run the reference Go benchmarks as well:
+There were no known changes to serialized and deserialized forms of types between versions 0.4.0 and 0.5.0.
 
-```sh
-cd benches
-make bench-all
-```
+## License
 
 Licensed under either of Apache License, Version 2.0 or MIT license at your option.
 

@@ 0,0 1,13 @@
+To run benchmarks on your system:
+
+```sh
+cd benches
+make bench
+```
+
+Or to run the reference Go benchmarks as well:
+
+```sh
+cd benches
+make bench-all
+```

@@ 1,7 1,12 @@
 #![forbid(unsafe_code)]
 //! # serde_bare
 //!
-//! An implementation of the BARE (<https://baremessages.org>) encoding format draft.
+//! An implementation of the [BARE](https://baremessages.org) encoding format draft for Rust
+//! using [Serde](https://serde.rs).
+//!
+//! Mailing list: https://lists.sr.ht/~tdeo/serde_bare
+//!
+//! Ticket tracker: https://todo.sr.ht/~tdeo/serde_bare
 //!
 //! ## Mapping from the Serde data model
 //!