x/tools/gopls: document a framework for configuration decisions

[findleyr]

We regularly get requests to add new configuration to gopls. These fall into different categories: some are UX-related, others are making certain parameters configurable, still others fundamentally change the way gopls behaves, in order for it to function better in certain environments.

We've learned the hard way that each new configuration option has a significant cost. Off the top of my head:

• Complexity: having a wall of settings can overwhelm users, and suggests that gopls doesn't work well out of the box.
• Maintainability: every new configuration option is itself a feature that must be implemented, maintained, or deprecated (and deprecation itself has its own burden).
• Testability: particularly for configuration that affects gopls' core operations (such as "memoryMode", "allowModfileModifications", or "completionBudget", each new configuration option can introduce a new dimension in a parameter space that must be (theoretically) be tested. Eventually, this parameter space becomes too large, and our test coverage fails us: example 1, example 2.

After experiencing the cost of our existing configuration, we increasingly push back on any new configuration. But absent context I think this can feel arbitrary to our users. Every request for new configuration comes with a good reason, and it's hard to argue that this benefit is more than offset by some abstract cost. Furthermore, we may sometimes reject reasonable configuration due to this reaction to past decisions.

Therefore, I think we need a formal framework for making decisions about new configuration, similar to the framework cmd/vet has for new analyses.

This issue tracks deciding upon and documenting that framework.

Again off the top of my head, I'd want something like this:

• Understandability: can the configuration be interpreted without understanding details of gopls internals? If not, then the configuration either needs to be re-framed, or gopls should be made to Just Work.
• Usefulness: would a large fraction of users use the configuration? If not, then it may not be worth the costs above.
• Necessity: is there there no way to choose a default behavior that works better for more users, such that the usefulness of the previous section is reduced?
• Superficiality / Orthogonality: does the configuration deeply affect the way that gopls works? Does it interact with other configuration? If yes to either question, then it should be avoided at all costs.

(I'll reiterate that these heuristics are just a starting point for discussion).

CC @golang/tools-team