go-toml v2 plan

[pelletier]

v2.0.0 has been released on 2022-04-27!

Go-toml v2 is the next major iteration of go-toml. Its goals are to provide a better API and faster performance.

Roadmap

• v2.0.0-alpha.x: early versions that change fast. 👈🏻
  • 📦 v2.0.0-alpha.1: first release with a working encoder and decoder.
  • 📦 v2.0.0-alpha.2: adding strict mode to the decoder.
• 📦 v2.0.0-beta.1: encoder and decoder feature parity with v1.
• 📦 v2.0.0-beta.2: code coverage of at least 95%.
• 📦 v2.0.0-beta.3: encoder and decoder at least faster than v1 and BurntSushi/toml.
• v2.0.0-beta.4: document editing structure. (why?)
• 📦 v2.0.0-beta.4: fix the known encoding/decoding bugs.
• 📦 v2.0.0-beta.5: add back missing encoder/decoder features.
• 📦 v2.0.0-beta.6: tooling and docker images ported to v2.
• 📦 v2.0.0-beta.7: small bug fixes and provide a clean (non-moved) build.
• --- v2.0.0-beta.8+: any amount of intermediate pre-releases until the API feels stable enough.
• 📦 v2.0.0-beta.8: bug fixes on the encoder.
• 📦 v2.0.0: 🍾

Help?

The development of go-toml v2 goes at the pace of whatever free time contributors can dedicate to the project. Here are three ways you can help the effort if you'd like:

• Submit pull requests for any issue linked in the v2 GitHub milestones (also linked in Roadmap).
• Use github.com/pelletier/go-toml/v2 in your projects! Report bugs, performance regressions, etc.
• Spread the word to anyone you think would be interested.

Related resources

• Requirements
• Decoder changes

[bep]

Just wanted to chime in and say that we have now switched to go-toml v2 for Hugo (I haven't released it yet, will do that next week,), but the upgrade was smooth sailing: Benchmarks are impressive and it fixed some issues I didn't know it would fix (most notable the date locality issue). A big thank you!

[pelletier]

Much appreciated! Glad it went well. Out of curiosity, do you have numbers to share for the benchmarks?

[bep]

@pelletier see the commit message in gohugoio/hugo@a3701e0

Note that that is a benchmark for the "whole Hugo thing" where the TOML config + front matter handling should play a minor part.

[pelletier]

Update: I am removing "Document Editing" from the requirements of go-toml v2. The release will move on without it.

We have made great progress in the core encoding and decoding feature of v2. The next major milestone was supposed to be v2.0.0-beta.4, featuring a brand new Document Editing API (requirements). For a few months now I have been playing with different ideas to provide an API that is flexible enough to cater to the many use-cases of document editing for TOML, but also easy to use from a developer standpoint. It turned out to require more time and energy from me than expected, and that does not include its actual implementation. It feels exacerbated by the fact that I am not a user of this library.

go-toml has always been a side-project for me, that I would work on for fun and learning. I am keen to continue working on the core of v2, especially on the performance aspect of it. However I am not going to invest my own time and energy on the Document Editing feature. I need to keep it light and fun.

I am happy to review proposals and accept pull requests for that feature if anyone wants to give it a shot. In the meantime, the v2 release will continue without this requirement, eventually replacing v1 without this feature built-in. I know some folks will be disappointed, but I believe that is the best direction for the project. The parser has been built in a way that should be solid foundation to support Document Editing – should just need to make some functions public and expose comments in the AST (small changes). For the record, here is the last revision of the Document API I was considering.

Thank you for your interest in go-toml!

[prashant-hspl]

Getting error while installing package using golang glide.
Error scanning github.com/pelletier/go-toml/v2: cannot find package https-github.com-pelletier-go-toml/v2.
When v2 will be release ?

Thank you.

[pelletier]

Hi! I am not familiar with glide, but I suspect you could pass it a specific version number (eg v2.0.0-beta.5).

v2 will be released when it is ready. I expect a little over a month from now, but no guarantees.

[pelletier]

Update: go-toml v2.0.0-beta.7 has been released! This is a huge milestone as it is the last planned version before the official 2.0.0 release! 🎉

There is still work that I'd like to do on the performance side, but that can easily be accomplished post-major version. Now is the time to chime in with any feedback on the API, and the stability of the v2 branch. I don't have a specific timeline for the cutover. Maybe in a month or so if I don't hear anything critical. When the major release happens, I will be closing all the v1-related issues, as I can't afford to maintain two versions. The only exception would be for a bug reported against v1 that is not confirmed as fixed in v2 (there are none at the moment).

Thank you to anyone who has been following so far!

[bep]

Upgrading to beta7 in Hugo as we speak, we've been running the beta6 without any known issues. Great work!