Globals configuration is unintuitive

[not-an-aardvark]

Previous issues: #4734, #5765

Background

Currently (ESLint v4.17.0), the globals value in a config file allows a user to configure globals for their project. The configuration looks like this, where each global is given a boolean value:

{
  "globals": {
    "Foo": true,
    "Bar": false,
    "baz": false
  }
}

Similarly, a boolean value can be used in a /* global */ comment directive to enable globals for a file:

/* global Foo: true, Bar: false, baz: false */

A value of true indicates that a global is allowed to be rewritten, and a value of false indicates that a global is read-only. This behavior is inherited from JSHint and JSLint.

Problem

There are a few disadvantages to the current behavior:

• Globals from an inherited config file cannot be turned off; they can only be reconfigured to true (rewritable) and false (read-only). This will make it more complex to enable a set of globals by default in the future (e.g. when we start supporting ES6 by default), because users will not be able to disable the globals.
• The correlation between true/false and "rewritable"/"read-only" is somewhat arbitrary, which makes it confusing to users. Anecdotally, I had been on the ESLint team for almost a year before I learned that /* global Foo: false */ would make Foo read-only. (I had previously thought that it would turn off Foo.)

The root cause of these problems is that there are three possible states of a global ("not present", "present but read-only", and "present and writable") but we only allow them to be configured with a boolean field.

Proposal

We should start allowing string values for globals. The possible values are (bikesheddable):

• readonly to indicate that a global is read-only (same as false)
• writable to indicate that a global is writable (same as true)
• off to indicate that a global is not present

To encourage people to use the new forms, we should deprecate the use of true and false for configuring globals. (However, for backwards compatibility, true and false would continue to be supported without a warning for the foreseeable future.)

[ilyavolodin]

As you correctly mentioned, this is due to legacy support for JSHint. I remember when it was implemented, there was some discussion about it, but that was pretty early on, and we decided to follow JSHint notation (seeing how it would help people migrate from JSHint without having to update all of their files manually).
I'm not opposed to enhancing this, but I think we have to keep it backwards-compatible.

[platinumazure]

I'd like to see this get implemented in 5.x. Curious to see what the rest of @eslint/eslint-team thinks.

[michaelficarra]

👍 but I noticed that you used "read-only" to describe the readonly option, so why not just use read-only?

[not-an-aardvark]

I don't feel strongly either way, but I would speculate that configuration keywords might be slightly easier to use when they don't have internal punctuation, because they would be easier to understand when spoken aloud (without needing to say something like "read dash only"), and they would be consistent with our other configuration keywords (none of which have punctuation). There is precedent for using the term readonly without a dash in C#.

A third option would be to just use the word readable for consistency with writable. That would have the possibility to be misleading if someone thinks a variable can be writable without being readable, but I'm not sure if this would actually cause much confusion in practice.

[ilyavolodin]

I'll mark it as accepted, since this has been up-voted by 5 members of TSC. In terms of the name, I would vote for either readonly or readable. Although I don't think latter conveys the right meaning.

[nzakas]

@aladdin-add it looks like you started working on this. Are you still working on this?