Docs: Add instruction re home-directory config files (refs #7729)

[jrpool]

Without this, config file in home directory makes 1 test fail.

What is the purpose of this pull request? (put an "X" next to item)

[X] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofixing to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)
Added instruction to disable any ESLint config file in home directory.

Is there anything you'd like reviewers to focus on?
Check my understanding that ESLint config files in home directory are deprecated (per comments of @platinumazure in issue #7729.

[eslintbot]

LGTM

[platinumazure]

Eek! I just quickly skimmed through the linked issue and I'm not sure where I said home directory configs are deprecated- that's not the case at all, and I feel bad if I misspoke! Would you mind telling me which comment you were looking at? On Oct 12, 2017 9:16 PM, "ESLint Bot" <notifications@github.com> wrote: LGTM — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9426 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARWesHAymkp3sOUQye6TfIawax7VI99ks5srsf0gaJpZM4P34bl> .

[jrpool]

Thanks for your quick reply, @platinumazure. One of your comments was: “it usually makes more sense to have all of your config files in your project directory. If you rely on a configuration in your home directory and you start sharing a project on GitHub or similar, then part of the linting configuration you've been using won't get to any of your fellow collaborators and your codebase will become inconsistent.”

Another reason for my inference of deprecation is that the tests don’t all pass when the user has a home-directory config file. The failing test is described as if the only prerequisite for its passing is the absence of a config file in /, but, in fact, the test’s passing requires that neither / nor ~/ contain an ESLint config file. The lack of any mention of the latter made me guess that a config file in ~/ is regarded at least as nonstandard.

Even if not deprecated, a config file in ~/ stops a new contributor, like me, from getting through the onboarding instructions without investigating and resolving the failure of one of the tests, so I am submitting this PR as a way to spare future contributors from this detour. I intend to submit another PR to make the texts in messages/no-config-found.txt and tests/bin/eslint.js accurately reflect the set of config files checked for.

If there is a better strategy for dealing with this issue, I welcome advice on that.

[not-an-aardvark]

In my opinion, we should fix the tests so that they don't require the user to delete files in their home directory. But I'm fine with adding this to the docs in the meantime.

[jrpool]

Thanks, @not-an-aardvark, for that thought. I agree, if ~/eslintrc.* is considered appropriate. I can look into such a fix.

[platinumazure]

Thanks, I didn't mean to imply deprecation. It's just that a config file in the home directory is not practical once you start working in a shared repository. In that case, you want the configuration for the project to be the same for all users, so individual users don't add their own style to the project and make it stylistically inconsistent. That said, it is unfortunate that our own unit test suite fails with the presence of a home directory config file. I'm sorry that this has lead to a poor contributing experience.

…

On Oct 12, 2017 10:07 PM, "Jonathan Pool" ***@***.***> wrote: Thanks, @not-an-aardvark <https://github.com/not-an-aardvark>, for that thought. I agree, if ~/eslintrc.* is considered appropriate. I can look into such a fix. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#9426 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AARWei04AC9HAhxMA8y1pEyihrwcFDiuks5srtQCgaJpZM4P34bl> .

[jrpool]

Thanks, @platinumazure. Then there seems to be a consensus that users should be cautioned about possible side effects of ~/eslintrc.*, but tests should not fail because of such a file. So I’ll try to propose a revision of the offending test.

As for my contributing experience, it has been anything but poor. I surveyed dozens of projects before choosing ESLint, and the combination of its clear instructions, its detailed codification of best practices, its enormous test repertoire, and people like you who respond intelligently within minutes to PRs, has completely validated my decision. The puzzle of 1 out of over 17,000 tests failing created a great opportunity to get started pitching in. You couldn’t have planned it better.