Status of this crate

[Ethiraric]

TL;DR: This crate will receive only basic maintenance and keep a stable API. saphyr will accept new features, at the cost of a less stable API

Initially, this crate was meant to be a replacement of yaml-rust. As it is today, it serves this specific purpose well.

However, we very rapidly have made API-breaking changes that required us to bump versions multiple times in a short timespan. This prevents us from evolving the library as we would like to. A balance needs to be found between improving the API and its usability and providing a library that people who already depend on yaml-rust can switch to easily if they do not want to spend the time migrating to another YAML library.

To that end, we have created a new set of libraries that is intended to evolve, whether it be performance, large API refactoring or new features, without being bound to the stability needs of the existing yaml-rust user base. This means that yaml-rust2 will receive fixes and very minor improvements if they can easily be ported, but no major change/feature will happen on this crate.

Users looking for a YAML library that will improve over time and are willing to pay the price of a bit of refactoring with new releases are directed to saphyr. At the time of this writing, both are very similar. If you happen to only use the parser (and not the Yaml object), you may use saphyr-parser instead.

[bitdivine]

Out of curiosity, why not bump the major version number? Make a branch called release-0 (as in major number 0) which contains the existing code and which gets only bugfixes and minor features. New code goes in main (or release-1 if you want). Anyone who wants to keep the old API can specify in their Cargo.toml that they don't want versions with the new major number. It seems as if semantic versioning was created exactly for situations like this.

[Ethiraric]

The philosophy of the 2 crates are different, and they will evolve at different rates. I do want this to be highlighted. If we have a release-0 branch, this means that every user of the 0 release who wants to check the code must know that they have to switch to a different branch.

Furthermore, I would like saphyr to be more than just a YAML library but a set of building blocks on which different levels of YAML utilities can build upon. This is a huge change from yaml-rust2 and changing the name of the project doesn't seem that incoherent. For instance, the parser can be used for parsing objects with the Yaml struct, but also with a potential serde integration. I have also created a benchmarking repository (which still has to be completed) that is based on the parser but needs no more than that.

[bitdivine]

Thank you for the clarification.

[chriskrycho]

This is helpful to know, so you might add this note to the README, possibly even using GitHub’s “admonition” syntax so it renders fancily, like so:

Important

TL;DR: This crate will receive only basic maintenance and keep a stable API. saphyr will accept new features, at the cost of a less stable API

Initially, this crate was meant to be a replacement of yaml-rust. As it is today, it serves this specific purpose well.

However, we very rapidly have made API-breaking changes that required us to bump versions multiple times in a short timespan. This prevents us from evolving the library as we would like to. A balance needs to be found between improving the API and its usability and providing a library that people who already depend on yaml-rust can switch to easily if they do not want to spend the time migrating to another YAML library.

To that end, we have created a new set of libraries that is intended to evolve, whether it be performance, large API refactoring or new features, without being bound to the stability needs of the existing yaml-rust user base. This means that yaml-rust2 will receive fixes and very minor improvements if they can easily be ported, but no major change/feature will happen on this crate.

Users looking for a YAML library that will improve over time and are willing to pay the price of a bit of refactoring with new releases are directed to saphyr. At the time of this writing, both are very similar. If you happen to only use the parser (and not the Yaml object), you may use saphyr-parser instead.

[Ethiraric]

That's a good idea, thanks! I've added the TL;DR only (I don't want this to occupy too much place in the README). There's a link to here for details.

[chriskrycho]

Makes sense. Thanks!