add MIGRATION GUIDE and CHANGELOG for this work

CHANGELOG.md

@@ -1,3 +1,19 @@
+# unreleased
+
+* Improve performance of Salsa by 3x and Chacha by 10x
+* Clearly distinguish at the type level various variants of chacha:
+    * Chacha as IETF (recommended)
+    * Chacha as original paper (64 bits counters)
+    * XChacha
+* Distinguish at the type level Salsa and XSalsa
+
+Breaking Changes:
+
+* Chacha, Salsa and Poly1305 interface changes to expect fixed sized array instead of slice, for stronger type safety
+  and less runtime error.
+* `Chacha::new_xchacha20::<ROUNDS>()` is now `XChacha::<ROUNDS>::init()`
+* `Salsa::new_salsa20::<ROUNDS>()` is now `XSalsa::<ROUNDS>::init()`
+
 # 0.4.4
 
 * fix legacy blake2b and blake2s `output_bits` interface returning a value 8 times bigger.

MIGRATION_GUIDE.md

@@ -0,0 +1,37 @@
+## Changing slice by array reference
+
+For slice to array reference changes of the form:
+
+```
+fn function(value: &[u8]) { ... }
+```
+
+tto:
+
+```
+fn function(value: &[u8; 12]) { ... }
+```
+
+In the case of the caller using array of the right size already,
+no changes need to be done. When the caller is using a subslice,
+one can use the following construction, from:
+
+```
+fn caller() {
+   let slice = &[....];
+   function(&slice[0..12]);
+}
+```
+
+to:
+
+```
+use core::convert::TryFrom; // not-necessary in latest rust edition
+fn caller() {
+   let slice = &[....];
+   function(<&[u8; 12]>::try_from(&slice[0..12]).unwrap());
+}
+
+Note the .unwrap() is just one way to (not) handle the error, and the caller
+should integrate the failing `try_from` case with the error handling
+conventions of the caller code.