Provide quick start information message at startup

[jpogran]

Problem Statement

The first run experience for this extension either on new install or on first use does not indicate to the user what needs to be done next in order to take advantage of the extension. At best this makes the user have to navigate to the extension readme in order to figure out what to do, at worst it leaves the user with inconsistent behavior or errors.

Expected User Experience

A VS Code user expects an extension to be usable immediately after installation. Extensions that require extra steps to be usable notify the user through pop-ups, prompts, walk throughs, or webviews to complete the required steps to enable the extension.

There are a few notable extensions that provider this: Gitlens, Docker, Go, Python, to name a few. Gitlens uses a webview with custom and extensive documentation, whereas Python and Docker uses a walkthrough. Extensions like Puppet attempt to detect what part is not setup correctly and inform the user with an error message instead of silent errors.

Proposal

We have several long term initiatives covering the first run experience: #737, #738, and #740, that will take awhile to complete but will solve some or all of this problem.

A short term solution to this would be a information message pop-up on install and/or on first use that would have a short 'quick start' set of instructions and a link to the online documentation. This 'quick start' text would inform the user of the quick two steps needed to 'activate' the extension fully. It would also explain that if those steps are not taken, then only syntax highlighting is available.

This would give us time to implement the longer term initiatives and provide a better user experience

[jpogran]

We can also go one step further past a warning message. We can pop a message that provides a button that opens the command palette to terraform: init current folder command, which is what the user has to do eventually. This works by immediately showing what is needed, as well as teaching the user about the built in commands and how they help.

[radeksimko]

We used to open a very similar popup from the LS in the exact same situation. This is more thoroughly described in #569 which was effectively a proposal for removal of that popup, which itself collected considerable amount of upvotes over a short period of time.

It is true that we didn't offer the "Don't check again" option back then, which may have been a contributing factor to the level of irritation.

More importantly though we made a flawed assumption that users would always edit modules which are init-able from where they're being edited. The reality is that users also edit modules which are never init-ed from their own directory, but only indirectly via a module call elsewhere.

For example:

network/main.tf

resource "cloud_network" "main" { ... }
resource "cloud_subnet" "public" { ... }
# ...

env/prod/main.tf

module "network" {
  source = "../../network"
  name = "Production"
  subnets = ["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24"]
}

env/dev/main.tf

module "network" {
  source = "../../network"
  name = "Development"
  subnets = ["10.5.0.0/24", "10.5.1.0/24", "10.5.2.0/24"]
}

The user can be editing the network module, but that module would only ever be init-ed from the context of env/dev or env/prod, not from within network.

There also seem to be users which never run init for any directory and also expect some editor comfort - but that may be rather unfortunate effect of init also initializing the state backend and affected users not having access to it from their workstations and therefore avoiding it.

Theoretically if/when Terraform provides a command/flag which allows just downloading providers without accessing state then this reason might go away.

---

I'm generally open to short-term solutions but with all of the above in mind I am hesitant to bringing such a popup back as a short-term solution, mainly because it makes the above flawed assumption and already seemed to have caused some irritation in the past.

As discussed earlier though I do think we should try to collect some telemetry data to understand how common of a problem this is - I am happy to create a separate issue for this to outline how and what kind of data we can collect.

[jpogran]

Closing this in favor of the linked work already planned/in progress.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.