prepare readme and changelog for 3.0~rc1

CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 3.0-rc1
+
+### Breaking changes
+
+see https://github.com/c-cube/ocaml-containers/issues/290 for a summary of
+a subset of these changes.
+
+packaging:
+
+- split the library into separate packages
+  `containers`, `containers-data`, and `containers-thread`.
+- delete `containers.iter` and merge parts of it into `containers-data`;
+- move `CCSexp` into the core library, remove `containers.sexp`.
+
+api:
+
+- remove slice APIs in string and array.
+- change pp functions to take unit printer for sep/stop/start (#295)
+- CCPair: use more standard name for some map functions (#316)
+- remove `CCKlist` from everywhere
+- CCGraph: remove deprecated module and function
+- rename `<op>_std_seq` to `<op>_seq`, making `Seq.t` the standard everywhere;
+  remove the old `<op>_seq` that were previously
+  deprecated in favor of `<op>_iter`.
+- CCVector: rename `shrink` into `truncate`
+- CCVector: rename `remove to CCVector.remove_unordered`
+- CCList: make mem compatible with the Stdlib by making `?eq` optional
+- CCVector: rename `filter'` into `filter_in_place`
+
+### Other changes
+
+- CI: add github actions in addition to travis
+- feat: add infix operators to `String`
+- feat: add opt.bind
+- CCResult: add `<$>` operator
+- CCResult: add `get_lazy`
+- put infix operators in `Infix` module, then include it
+- ccnativeint: complete CCNativeint with regards to CCInt
+- Int64: complete CCInt64 with regards to CCInt
+- CCInt32: complete CCInt32 with regards to CCInt
+- implement `CCInt.sign` using `CCInt.compare`
+- CCInt: include module Int for ocaml >= 4.08
+- CCInt: add `of_float`
+- CCInt: add `of_string_exn`
+- add `CCResult.get_lazy`
+- add `Int.popcount` operator
+- CCFloat: add `pi`
+- CCFloat: add `of_string_opt`
+- fix: expose `always_eq`/`never_eq` in `CCEqual`
+- string: add optional `cutoff` arg on `String.edit_distance`
+- CCVector: add `remove_and_shift`
+- CCArray: add optional argument eq to mem
+- CCSexp: Escape empty atoms
+- substitute 'Pervasives' with 'Stdlib'
+- CCFormat: add `exn` combinator
+- IO: add `copy_into` for transferring data between channels
+
+- Extend benchmark: `to_array`, cons and `cons_fold`
+- Extend benchmark: Sek, iter and pop
+- benchmark for memory usage of data structures
+
+And many, many bugfixes.
+
 ## 2.8.1
 
 - add missing `CCVector.of_iter`

README.md

@@ -41,6 +41,52 @@ Some of the modules have been moved to their own repository (e.g. `sequence` (no
 
 ## Migration Guide
 
+### To 3.0
+
+The [changelog's breaking section](CHANGELOG.md) contains a list of the breaking
+changes in this release.
+
+1. The biggest change is that some sub-libraries have been either turned into
+  their own packages (`containers-thread`, `containers-data`),
+  deleted (`containers.iter`),or merged elsewhere (`containers.sexp`).
+  This means that if use these libraries you will have to edit your
+  `dune`/`_oasis`/`opam` files.
+
+  - if you use `containers.sexp` (i.e. the `CCSexp` module), it now lives in
+    `containers` itself.
+  - if you used anything in `containers.data`, you need to depend on the
+    `containers-data` package now.
+
+2. Another large change is the removal (at last!) of functions deprecated
+  in 2.8, related to the spread of `Seq.t` as the standard iterator type.
+  Functions like `CCVector.of_seq` now operate on this standard `Seq.t` type,
+  and old-time iteration based on [iter](https://github.com/c-cube/iter)
+  is now named `of_iter`, `to_iter`, etc.
+
+  Here you need to change you code, possibly using search and replace.
+  Thankfully, the typechecker should guide you.
+
+3. `Array_slice` and `String.Sub` have been removed to simplify the
+  code and `String` more lightweight. There is no replacement at the moment.
+  Please tell us if you need this to be turned into a sub-library.
+
+4. Renaming of some functions into more explicit/clear names.
+  Examples:
+
+  * `CCVector.shrink` is now `CCVector.truncate`
+  * `CCVector.remove` is now `CCVector.remove_unordered`, to be
+    contrasted with the new `CCVector.remove_and_shift`.
+  * `CCPair.map_fst` and `map_snd` now transform a tuple into another tuple
+    by modify the first (resp. second) element.
+
+5. All the collection pretty-printers now take their separator/start/stop
+  optional arguments as `unit printer` (i.e. `Format.formatter -> unit -> unit`
+  functions) rather than strings. This gives the caller better control
+  over the formatting of lists, arrays, queues, tables, etc.
+
+6. Removal of many deprecated functions.
+
+
 ### To 2.0
 
 - The type system should detect issues related to `print` renamed into `pp` easily.