Add ./pants generate-pants-ini for first time users to generate pants.ini with sensible defaults (#7448)

### Problem
Our first-time [setup instructions](https://www.pantsbuild.org/install.html#recommended-installation) are harder than need be. Currently, before being able to do anything with Pants, you must:

1) curl `pants`
1) `chmod +x pants`
1) `touch pants.ini`
1) Copy and paste `[GLOBAL]` into the file.
1) Run `./pants -V` or decide you want to pin a different value.
1) Copy and paste that value into a new line `pants_version`.

Instead, we could simplify the instructions to:

1) curl `pants`
1) `chmod +x pants`
1) `touch pants.ini`
1) `./pants generate-pants-ini`

Once we add instructions on `pants_runtime_python_version`, this would get even more complex.

Simplifying the onboarding process should make it easier for us to retain first time users. There are a lot of new concepts they already have to learn, e.g. BUILD files, targets, and goals. The less overwhelming we can make this process, the better.

Refer to https://pantsbuild.slack.com/archives/CBNMV1LRH/p1552506655047900 for the original discussion around this idea and pantsbuild/setup#45 for the original implementation until we realized this should be a goal.

### Solution
Add new `./pants generate-pants-ini` to setup the initial value with defaults as follows:
* `pants_version` == version used during the run
* `pants_runtime_python_version` == version used during the run

We do not provide options to override these defaults, because this is meant for first time users who would not yet be familiar with options or discovering them via `--help`. Further, they can change the defaults by rewriting `pants.ini`.

We also do not allow this command to be ran on pre-existing `pants.ini`, because Python's configparser would strip all comments and mess up the indentation. Instead, users should simply modify their file.

### Result
If there is no content in `pants.ini`, we will print this and update `pants.ini` accordingly:
```
Adding sensible defaults to /Users/eric/DocsLocal/code/projects/pants/pants.ini:
* Pinning `pants_version` to `1.15.0rc0`.
* Pinning `pants_runtime_python_version` to `3.6`.

You may modify these values directly in the file at any time. The ./pants script will detect any changes the next time you run it.

You are now ready to use Pants!
```

If there is already content, we will fail the task and explain how to update, including the sensible defaults as a suggested edit.

### TODO: allow missing `pants.ini`
Currently, Pants fails to execute if there is no `pants.ini` in the buildroot. This does not seem intentional, as an empty `pants.ini` will fix the issue. 

As a followup, we should allow a missing `pants.ini` and then use this command to generate the file. It will allow us to avoid having to instruct `touch pants.ini`.

### TODO: Updating docs
We cannot update the docs to reflect this new option until 1.15.0 is released. The setup repo defaults to the most stable version, and this goal will not be available in 1.14.0 so would confuse people.

Author: Eric-Arellano

src/python/pants/core_tasks/generate_pants_ini.py

@@ -0,0 +1,46 @@
+# coding=utf-8
+# Copyright 2019 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+import os
+import sys
+from textwrap import dedent
+
+from pants.base.build_environment import get_default_pants_config_file
+from pants.base.exceptions import TaskError
+from pants.task.console_task import ConsoleTask
+from pants.version import VERSION as pants_version
+
+
+class GeneratePantsIni(ConsoleTask):
+  """Generate pants.ini with sensible defaults."""
+
+  def console_output(self, _targets):
+    pants_ini_path = get_default_pants_config_file()
+    python_version = ".".join(str(v) for v in sys.version_info[:2])
+    pants_ini_content = dedent("""\
+      [GLOBAL]
+      pants_version: {}
+      pants_runtime_python_version: {}
+      """.format(pants_version, python_version)
+    )
+
+    if os.stat(pants_ini_path).st_size != 0:
+      raise TaskError("{} is not empty. To update config values, please directly modify pants.ini. "
+                      "For example, you may want to add these entries:\n\n{}".format(pants_ini_path, pants_ini_content))
+
+    yield dedent("""\
+      Adding sensible defaults to {}:
+      * Pinning `pants_version` to `{}`.
+      * Pinning `pants_runtime_python_version` to `{}`.
+      """.format(pants_ini_path, pants_version, python_version)
+    )
+
+    with open(pants_ini_path, "w") as f:
+      f.write(pants_ini_content)
+
+    yield ("You may modify these values directly in the file at any time. "
+           "The ./pants script will detect any changes the next time you run it.")
+    yield "\nYou are now ready to use Pants!"

src/python/pants/core_tasks/register.py

@@ -8,6 +8,7 @@
 from pants.core_tasks.clean import Clean
 from pants.core_tasks.deferred_sources_mapper import DeferredSourcesMapper
 from pants.core_tasks.explain_options_task import ExplainOptionsTask
+from pants.core_tasks.generate_pants_ini import GeneratePantsIni
 from pants.core_tasks.list_goals import ListGoals
 from pants.core_tasks.login import Login
 from pants.core_tasks.noop import NoopCompile, NoopTest
@@ -76,6 +77,9 @@ def register_goals():
   task(name='options', action=ExplainOptionsTask).install()
   task(name='targets', action=TargetsHelp).install()
 
+  # Set up pants.ini.
+  task(name="generate-pants-ini", action=GeneratePantsIni).install()
+
   # Stub for other goals to schedule 'compile'. See noop_exec_task.py for why this is useful.
   task(name='compile', action=NoopCompile).install('compile')
 

tests/python/pants_test/core_tasks/BUILD

@@ -35,6 +35,18 @@ python_tests(
   ],
 )
 
+python_tests(
+  name = 'generate_pants_ini',
+  sources = ['test_generate_pants_ini.py'],
+  dependencies = [
+    'src/python/pants:version',
+    'src/python/pants/base:exceptions',
+    'src/python/pants/core_tasks',
+    'tests/python/pants_test:task_test_base',
+    '3rdparty/python:configparser',
+  ],
+)
+
 python_tests(
   name = 'prep_command_integration',
   sources = ['test_prep_command_integration.py'],

tests/python/pants_test/core_tasks/test_generate_pants_ini.py

@@ -0,0 +1,32 @@
+# coding=utf-8
+# Copyright 2019 Pants project contributors (see CONTRIBUTORS.md).
+# Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+from __future__ import absolute_import, division, print_function, unicode_literals
+
+import configparser
+
+from pants.base.exceptions import TaskError
+from pants.core_tasks.generate_pants_ini import GeneratePantsIni
+from pants.version import VERSION
+from pants_test.task_test_base import ConsoleTaskTestBase
+
+
+class GeneratePantsIniTest(ConsoleTaskTestBase):
+
+  @classmethod
+  def task_type(cls):
+    return GeneratePantsIni
+
+  def test_pants_ini_generated_when_empty(self):
+    temp_pants_ini_path = self.create_file("pants.ini")
+    self.execute_task()
+    config = configparser.ConfigParser()
+    config.read(temp_pants_ini_path)
+    self.assertEqual(config["GLOBAL"]["pants_version"], VERSION)
+    self.assertIn(config["GLOBAL"]["pants_runtime_python_version"], {"2.7", "3.6", "3.7"})
+
+  def test_fails_when_pants_ini_is_not_empty(self):
+    temp_pants_ini_path = self.create_file("pants.ini", contents="[GLOBAL]")
+    with self.assertRaisesWithMessageContaining(TaskError, temp_pants_ini_path):
+      self.execute_task()