What is the path to 1.0?

[epage]

• TOML has matured with a 1.0 spec
• toml_edit has matured with
  • Support for 1.0
  • A more capable API
  • Drop-in replacement for toml-rs
  • Performance that nearly matches toml-rs

Since toml_edit doesn't involve interoperability between crates (like say serde), we don't have to have perfection for 1.0, so what would be blockers?

[epage]

#192 seems like the most likely candidate for me because a part of the API does not behave as expected (to_pretty_string isn't pretty).

However, that is one specific corner, is it really important enough to block 1.0?

[epage]

I marked it as breaking-change, because the straightforward solution would involve breaking the API. We could name the new functions differently and mark the old functions as deprecated, allowing us to maintain compatibility when this does get implemented.

[ordian]

I think we should think in terms of semver compatibility, so changing the output of to_pretty_string would be considered as a non-breaking change as it won't introduce compile errors downstream. We need to think about API naming, but largely, I think we're ready for 1.0. Maybe it would be good to resolve #163 before that.

[epage]

We need to think about API naming

Mind doing a pass through the API for naming and structure feedback?

One part I'm torn on is I like it when the core parts of the API are obvious in docs (e.g. Document, Value) rather than burrried among the noise (e.g. Entry, iterators) but finding the right depth / organization balance is hard.

I think we should think in terms of semver compatibility, so changing the output of to_pretty_string would be considered as a non-breaking change as it won't introduce compile errors downstream.

To clarify, my original thought for to_pretty_string is it would be built on a replacement for the auto-format functions. That was the breaking change I was expecting with that. However, we could always keep the existing fmt functions and just mark them as deprecated as we see fit.

Maybe it would be good to resolve #163 before that.

#163 doesn't involve any breaking change and it seems minor enough (dotted keys aren't too common, it does what people should already be doing), that I'm not too concerned.

[epage]

Looking at the docs, I realized we could use #229