Formalize current state as "1.0"

[moshez]

TOML is now relied upon in the wild by big projects -- pyproject.toml and cargo.toml among others, which are implemented, respectively, in pip master (as yet unreleased, but probably soon) and cargo 1.23 (at time of writing) -- both using semver and having >1.0 versions.

This means that effectively TOML cannot really break backwards compatibility without breaking the basic tool for the top language and the most loved language. While one can quibble with the measurements of Python and Rust, one cannot argue that they are important tools which currently have baked TOML deep into the specification of their build tools.

If it is impossible to just freeze the current state as 1.0, there needs to be a clear indication of what things need to be resolved for 1.0, issues made for them and at least some semblance of a timeline for solving them -- or a request for a co-maintainer who can help shepherd 1.0.

Please do not close this bug until one of these things is done.

[moshez]

See also #513

[EdorianDark]

See also #330

[pradyunsg]

pyproject.toml and cargo.toml

This is why I'm made the push for TOML to become v1.0, a few months back.

there needs to be a clear indication of what things need to be resolved for 1.0

As I understand, there's #499, #502 and #510 which should be finished up before @mojombo would make a 1.0 release; along with a website, maybe even #465.

I'm not someone who's making the decisions on this project anyway, so, there's that.

[moshez]

@pradyunsg your efforts on v1.0 have not gone unnoticed, or unappreciated! You have been instrumental in getting it to this state, which, in my opinion, can just call 1.0.

Re: #499 -- what do the current parsers do? Would using paths in keys work? If not, it can wait until after 1.0.

Re: #502 -- This does not sound like something that should hold up 1.0, since none of the current parsers use the ABNF anyway.

Re: #510 -- Ditto.

Re: #465 -- Why would a mime type hold up 1.0?

I am also not sure why a website is a dependency for 1.0.

All these things sound like they could wait for a 1.1 release.

@mojombo -- can you clarify which issues you think are blockers for 1.0, and mark them as such?

[pradyunsg]

@pradyunsg your efforts on v1.0 have not gone unnoticed, or unappreciated! You have been instrumental in getting it to this state, which, in my opinion, can just call 1.0.

Thanks for the kind words. ^>^

---

Re: #499 -- what do the current parsers do? Would using paths in keys work? If not, it can wait until after 1.0.

They don't accept it but this is a powerful thing. It shouldn't take much time and I already have a half-baked PR (#505). This is something that can wait for 1.1 though.

Re: #502 -- This does not sound like something that should hold up 1.0, since none of the current parsers use the ABNF anyway.

Re: #510 -- Ditto.

I'd say it's the "formal" part of the TOML specification. Even if the parsers don't use it directly, the behaviour is concretely defined there. Anyway, we could just drop these for now and be done with it but yeah, it's not ideal.

Re: #465 -- Why would a mime type hold up 1.0?

It won't. It's more of a nice-to-have. :)

I am also not sure why a website is a dependency for 1.0.

It'd been stated before somewhere in this repo that Tom wanted that for a 1.0 release.

---

I won't mind having the current state marked TOML 1.0. I would strongly prefer to see #499 and #510 resolved before a 1.0 is marked.

I think I might be able to finish up the PRs for them this week.

Let's see.

[pradyunsg]

both using semver and having >1.0 versions.

Off Topic: Saying PEP 518 or pip use "semver", would be wrong. See PEP 440 for the versioning scheme used in the Python ecosystem.

[moshez]

That versioning scheme just says how pip parses other packages' version number: it's compatible with semver, but does not mandate it. Pip itself uses semver, e.g., upgrading major number for incompat changes -- see https://pip.pypa.io/en/stable/news/ for 9.0.0.

[pradyunsg]

I'd rather not digress here. :)

[moshez]

@mojombo I think we need feedback here. What issues do you think are must-have for 1.0, considering it's already depended on in the wild by big projects?

[aklaver]

I am starting a project in which my plan is to use TOML. I would feel more secure knowing that TOML is planning soon to move off what is now a 3 year old spec.

[pradyunsg]

Coming back to this now, I'm gonna try to plot a path for a v1.0.0 of TOML:

• Merge Disallow ASCII delete in Literal strings #534 :P
• Finalize on Allow keys in key-value pairs to be paths #499; seems like we're almost there -- @mojombo needs to take a look.
  • I'll happily draft up a PR. :)

Okay. So, it seems we're almost there.

Now, if @mojombo wants a website, I'm pretty sure it'll be pretty simple to setup. (I imagine it'll be a Jekyll site hosted on GH Pages). It can be held off until after a release IMO.

[mojombo]

@pradyunsg What is your recommendation for #499?

[pradyunsg]

@mojombo I'll post them there. :)

[takluyver]

I see that #534 was merged and #499 was closed. Can we expect a version 1.0 soon? 😃

[lmna]

Is it okay to release 1.0 with toml.abnf marked as "work-in-progress"? ( How would we convince ourselves that toml.abnf does not contradict the Spec? A comprehensive testsuite would be helpful, but it does not exist.)

Should toml.abnf be removed completely from the scope of 1.0 ?

[mojombo]

I had a realization on the airplane today, which is that in trying to make everything perfect for v1.0.0, I've been delaying everything pointlessly. Which is dumb.

I just released the current master branch as v0.5.0 and further clarified the stability of the software and intended backwards compatibility of v1.0.0. Hopefully this will encourage implementations to get up to speed with the many improvements that have been added since v0.4.0 and ease the transition to v1.0.0 once we've nailed down the last few technicalities.

I know many of you are impatient for v1.0.0 and I understand completely. At the same time, I think it's extremely important to make it solid. This kind of spec works best when major versions don't need to be changed with a bunch of patches afterwards to fix up and clarify edge cases.

[mahmoud]

0ver rides on! Keep flying that flag, Tom!

[mojombo]

@mahmoud Hah, the irony is not lost on me, trust me. I'll still hide behind the banner of "specs are not libraries" and conservative versioning is better, as can be easily witnessed by the discussion in #522. =/

[pradyunsg]

See #617.

[pradyunsg]

There's https://github.com/toml-lang/toml/projects/1 for tracking progress to 1.0 now.

[waldyrious]

For future reference, after three release candidates, TOML 1.0 was released on 12 January 2021! 🎉

[repentsinner]

Amazing, thanks team!!