TOML 1.1.0

[pradyunsg]

I like having issues for tracking releases, to have a single point for discussion.

[pradyunsg]

I think after #924, it'll be a good moment to cut an 1.1.0-rc1.

[arp242]

Edit 2023-06-03: all of this is now done.

I think it would be nice to also update the toml-test to TOML 1.1; I added a test for \e some time ago, but that's about it 😅

There are two parts to this; the first is updating https://github.com/burntSushi/toml to support TOML 1.1, which is needed because toml-test uses it. This is just something I need to spend a bit of time on; I don't expect that will be too difficult.

The second part is actually adding tests for TOML 1.1, for both valid and invalid edge cases, and this is something people here can help out with. This also requires identifying some of the "invalid" tests that are now "valid"; I added a -toml flag to specify the TOML version, so we can keep it compatible with 1.0 and 1.1 (specified in version.go).

At any rate, if people feel interested to spend some time on thinking of test cases and making a PR then that'd be appreciated.

[eksortso]

On #926, I recommended that we set up a Project here for TOML v1.1.0. (Guess we're just using major.minor for version numbers now?) That would direct attention to the issues and tasks that still need to be done. We had one for v1.0.0 prior to the release candidates. Even if it's small, think it would be worth doing?

By the way, #924 may be split into pieces; I already submitted #929. You may want to move the cutoff.

[ChristianSi]

I've tried doing a little triage regarding all open issues and PRs, to see whether and how urgently they should become part of 1.1.0. Here's the result:

Should definitively be included (in some way or other):

• Clarify Unicode and UTF-8 references #929: this is really just a small wording change.
• Permit more control characters in comments #924: this incorporates the changes from Clarify Unicode and UTF-8 references #929 and so should be handled afterwards; it too is a fairly minor change, but it changes the substance of the spec, so @pradyunsg might conceivably reject it. But in any case it should be decided upon.

To be decided whether we include them:

• Clarify sub-millisecond precision is allowed #805: it is just a tiny change to two examples; it makes sense to decide whether it goes in or is rejected before the next release.
• clarify string descriptions #875: this too is a relatively small wording change, which might be accepted or rejected.
• Define appropriate implementation behaviors for extreme values #538: it's unclear whether this will result in any changes, but it probably makes sense to give it some thought before the release.
• Add syntax for hexadecimal floating point values #562: this would add new syntax, so we may accept it, postpone it for possible inclusion in a future version, or reject it altogether.
• Feature request: Add a duration/timedelta type #514 – related PR: Proposal to add a duration type #717: this would add a new datatype, which might be accepted (in some way), postponed, and rejected.
• Added Schema validator specification #116: this is pretty old, I don't know if it's still wanted or relevant. But it might make sense to decide on it some way or the other instead of just letting it rot.

Not essential, but would be nice to have:

• Newlogo #909 – related issue: New logo design concepts #828: this has been hanging for quite a while and for no good reason I can see; it's not really relevant for a new version, but would be good to act upon to improve TOML's corporate identity.
• Maintainance and onboarding new maintainers #895: clearly we can do a new release with the existing maintainer team, but the maintainer bottleneck is still noticeable, so it would certainly be helpful if there was some substantial progress on this ticket.
• Make toml-test the standard test suite for checking compliance of implementations #585: not really a part of the spec, but progress on this would be good as well.

To be started afterwards:

• TOML as an RFC? #870: there was already some talk that the 1.1.0 release might be a good starting point for an RFC (if and when we decide we want one), so the release must be done first before this can be tackled.

New syntax or features that are probably beyond the scope of TOML 1.1 (if they ever come):

• Add nicer syntax for file sizes #912: frankly I think we could just reject this; but if it comes, I don't think it'll come soon.
• Proposal: TOML Schema #792: this is a big topic that's probably best treated separately.
• Optionally supported implementation-defined values #707: if this comes, it would be a big topic that'll require a lot of work, so I don't see it as a possible part of 1.1. Frankly I also see it as a violation of TOML's "minimalism" principle and would therefore be in favor of closing it altogether.
• Will custom type syntax be good for TOML health? #603: similar to Optionally supported implementation-defined values #707 in scope and consequences.

Definitively beyond the scope of any TOML 1.x release, since it would be a breaking change:

• Possible positional restrictions on table definitions #446: @pradyunsg: maybe one could add a "post-1.x" label for this, since it's incompatible with TOML 1.0 and so couldn't ever come before 2.0. Though frankly I think one could just close it, since "You can put tables in any order (except where arrays of tables are involved)" has always been a core element of TOML's philosophy and I don't really see it going away.

[marzer]

I really would like #562 to be included in the next version. We mandate that 'reals' be IEEE754 binary64 floating-point, but we have no way of expressing the full range of those exactly in a TOML document, and sometimes you need to do just that.

Of course an application can ask users to express this as a [sign, exponent, mantissa] triplet, but that's goofy.

[ChristianSi]

I'd also second @awvwgk's proposal to do a RC candidate first (once everything seems taken care of) – announce it widely, what for 2 months to see if anything comes up and if that's not the case (beyond typofixes and such), release 1.1 final after the 2 months. If not, release RC-2 and iterate. That's how we did it with 1.0, and it seems to have worked well enough.

[mcarans]

Now that what is under "Should definitively be included (in some way or other)" is merged, what is the process to decide for the ones under "To be decided whether we include them" in this comment?

[mcarans]

I think after #924, it'll be a good moment to cut an 1.1.0-rc1.

@pradyunsg How are things going towards the release candidate?

[pradyunsg]

@pradyunsg How are things going towards the release candidate?

You can see this by looking at the milestone @mcarans -- https://github.com/toml-lang/toml/milestone/1.

[pradyunsg]

The way I've got things scoped out for 1.1.0 is that we'll have to resolve the unicode keys question and move forward with rc1. I don't plan to add any more new syntax/data type in TOML 1.1.0.

https://github.com/toml-lang/toml/milestone/1 has the issues that I intend to "definitely close out" on that topic, after which it's going to be the mechanics of cutting a new TOML release.

[pradyunsg]

Of course, immediately after I post that, I notice that there's also some disucussion about the changes to comment's permitted control characters so added that into the milestone as well.