Designate pants.ini as legacy, but still supported, in docs

[Eric-Arellano]

We decided to not (yet) deprecate pants.ini because it causes too much friction for users at the same time that they're dealing with deprecating globs() and --test-fast. Further, the code to support pants.ini is not very painful to support as it is well-isolated (although, it would allow us to simplify things if we could always assume TOML).

But, we don't want to have to refer to both TOML and INI in our docs and user messages. So, we strike a compromise where we always assume TOML in our docs, but allow our code to work with both.

To reflect this decision, we update our docs to have a section explaining how INI works and pointing to a script to migrate to TOML. That is the only section in our docs that we should ever mention INI.

[Eric-Arellano]

(Added so many of you all because this PR is mostly a discussion and decision for the project; not really code review.)

[cosmicexplorer]

Have we discussed this change with pants-devel?

[blorente]

I was talking about this with @olafurpg the other day, and we reasoned that pants.ini is hardcoded in so many systems at Twitter that it would be extremely hard for us to migrate Twitter off of it.

While I think toml is the better alternative, I don't think we can realistically stop using pants.ini in a few release cycles, and we'd need this to continue existing as an alternative. This is just my opinion though, @stuhood 's or @illicitonion 's might differ.

[Eric-Arellano]

Have we discussed this change with pants-devel?

Not yet, because I wanted to get all of your thoughts first. If there were any doubts on whether we should do this (as it turns out there are) and we couldn't reach a decision, reaching out to pants-devel would be a great idea to get more user feedback.

I was talking about this with @olafurpg the other day, and we reasoned that pants.ini is hardcoded in so many systems at Twitter that it would be extremely hard for us to migrate Twitter off of it.

While I think toml is the better alternative, I don't think we can realistically stop using pants.ini in a few release cycles, and we'd need this to continue existing as an alternative.

Good to know!

I propose, then, that we keep support for pants.ini for a much longer time (possibly forever?). The code is not very expensive to support both formats. We'd be able to simplify if we dropped INI, but that code is 100% abstracted away in config.py and parser.py so the deprecation isn't as much a benefit in terms of code as something like removing globs().

Rather, the expense of supporting both formats is in documentation. It's difficult/clunky for us to refer to both pants.toml and pants.ini everywhere.

So, the proposal is that we keep support for INI, but mark pants.ini as something like "Legacy INI file format" and use TOML everywhere in our documentation, such as the first time install guide and config snippets we put in deprecation warnings. The only place we'd refer to it is in options.md on a section called "Legacy INI file format" which explains the differences from TOML.

--

If we agree to this plan, the next steps would be:

1. Add "Legacy INI file format" section to options.md.
2. Send an email to pants-devel explaining that we encourage them to migrate to pants.toml, but it's their choice. They can use either or even intermix the two.
   • Long term, maybe we encourage an incremental migration thanks to being able to intermix the two?

[blorente]

I like this change a lot more, thanks a lot for reaching out @Eric-Arellano

[Eric-Arellano]

As decided above, this PR is now updated to no longer deprecate INI, but to only mark it as legacy in our docs. This is ready for review :)

[stuhood]

Thank you!

I was talking about this with @olafurpg the other day, and we reasoned that pants.ini is hardcoded in so many systems at Twitter that it would be extremely hard for us to migrate Twitter off of it.
FWIW, parsing pants.ini has never been a suggested approaching for external integrations... ./pants options supports rendering options as JSON, and IDE integrations should prefer that. cc @wisechengyi

Having said that, I agree that having breathing room to make that migration would be a very good idea, so thank you for bumping this out a bit.