Better formatting and parameter documentation when initializing a project

[jasonkuhrt]

I am relatively new to Haskell and have no experience with Stack. I started to dive in today and found an experience that I think can be improved which is related to better documentation for the user on what each required parameter accepts as values and why its needed. Some are obvious (author-email, author-name, etc.) but others are not, such as category and license.

The following shows my rough sketch of an alternative. The first codeblock is the output as I saw it today, and the second codeblock is my sketch of what might be better for the user.

Before

❯ stack new weather simple
Downloading template "simple" to create project "weather" in weather/ ...
The following parameters were needed by the template but not provided: category
You can provide them in /Users/jasonkuhrt/.stack/config.yaml, like this:
templates:
  params:
    category: value
Or you can pass each one as parameters like this:
stack new weather simple -p "category:value"
Writing default config file to: /Users/jasonkuhrt/projects/weather/weather/stack.yaml
Basing on cabal files:
- /Users/jasonkuhrt/projects/weather/weather/weather.cabal

Checking against build plan lts-3.14
Selected resolver: lts-3.14
Wrote project config to: /Users/jasonkuhrt/projects/weather/weather/stack.yaml

After

Note: Its easy to imagine colours further aiding in helping communicate this information.

$ stack new weather simple
==> Downloading template "simple" to create project "weather" in weather/ ...
--> Warning: Missing Parameters    
    The following parameters were needed by the template but not provided:

    • category
      The kind of project being created? Valid values are:
      Data | App | Foo | Bar | ...

    • license
      Under what terms are others allowed to use this project? Valid values are
      any SPDX License (see spdx.org/licenses) eg:
      LGPL-2.0 | MIT | ISC | BSD-2-Clause 

      Learn more about many of these choices at choosealicense.com/licenses

    Parameters can be provided either in ~/.stack/config.yaml eg:

      templates:
        params:
          category: VALUE
          license: VALUE

    Or as command line arguments eg:

      $ stack new weather simple -p "category:value"

==> Writing default config file
    weather/stack.yaml
--> Based on cabal files:
    weather/weather.cabal
==> Checking against build plan lts-3.14
==> Selected resolver: lts-3.14
==> Created project config
    weather/stack.yaml

Thanks for your consideration.

[harendra-kumar]

That looks great! Thanks for taking time to write this. I am all for it.

Some of the code generating this output is shared with stack init. We may have to consider reformatting that as well. If we decide to do arrow formatting then it should be done for all commands wherever applicable for consistency but indentations, line spacings and other content is fine anyway. I remember @luigy was talking about fancy colors in the output in one of the issue updates.

[jasonkuhrt]

That looks great! Thanks for taking time to write this. I am all for it.

My pleasure, I'm glad that I contributed something useful.

If we decide to do arrow formatting then it should be done for all commands wherever applicable for consistency

Yeah. I don't know the stack commands and their output(s) well enough to make a complete suggestion here. I loosely implied a system above where:

==>   Is a top-level Section
-->   Is a sub-level Section

But I presume this is just scratching the surface of what a thought-out system of "information architecture" on the outputs could be. Also, I was making best-guesses as to what the hierarchy is, I surely got it somewhat wrong. Anyways, a first step might be a very minimal but correct layer of formatting...unless:

Has anyone on the stack team or in the community considered all CLI output to be in a structured data such as JSON? The advantage of this would be that interfaces over this data could be strictly independent programs. For a program aiming to display JSON to the terminal its type might simply be JSON -> IO String. Other programs might be focused on bridging the JSON to other interfaces such as IDEs. This separation of content and presentation would allow stack core to focus on the ideal data schema, merely facilitating issues like this one (e.g. the ==>, --> hierarchy).

I remember @luigy was talking about fancy colors in the output in one of the issue updates.

Hey @luigy! : )

[jasonkuhrt]

For what it's worth I will say that beautiful and great command line interface experiences is soemthing I am unusually excited about. Combined with my enthusiasm for Haskell, this issue of improving the user experience of CLI output is something I would be happy to contribute effort to. For the time being, I am not competent enough in Haskell or understand stack well enough to dive into this, but maybe over time that would change and the project would have an opening for such contribution.

[harendra-kumar]

Welcome! I too care a lot about user interfaces and user experience, especially easy diagnosability of problems by users. If you wish to you can send a PR with relatively easy, localized changes, if there are changes which are more involved they can be done later.

[jasonkuhrt]

If you wish to you can send a PR with relatively easy, localized changes

That sounds maybe doable! Can you direct toward the modules that I should focus on?

[mgsloan]

Yeah, it'd be great to polish output, particularly for someone enthusiastic with a fresh pair of eyes :). I've opened up this related issue: #1912

A cool idea that @luigy suggested in the past to beautify the build process a bit would be to have a single line progress indication, like ocaml build (IIRC). In other words, it would tell you that currently it's Progress 35/120 (building X, installing Y, configuring Z). Then, you'd just get one line of output per package saying that it's been installed / tested / whatever.

[harendra-kumar]

@jasonkuhrt stack new and stack init flow starts at newCmd/initCmd in Main.hs which will lead you to new in New.hs and initProject in Init.hs.

[luigy]

@jasonkuhrt 👍 get pumped with issues like this :)

Note: Its easy to imagine colours further aiding in helping communicate this information.

I wish the excitement bar across was higher for this :)

Progress 35/120 (building X, installing Y, configuring Z)

Yes, I would like to pick this one up again and see more enthusiasm

[jasonkuhrt]

Status Update:

I am currently working on a command line weather application. Its my first serious Haskell application and should get me pretty deep into working with the terminal with Haskell. Once I finish this project, or at least make significant headway, I will come full circle to this issue and make some contributions.

[mpilgrem]

Closing because Stack has no way of knowning what tag names will be used in a specified template and, so, is not in a position to provide any assistance about how the tag name is intended to be used in the template in question. It is for new template designers to use tag names that are likely to be meaningful and existing 'central' templates are now 'baked in' to the ecosystem. The formatting of the message has improved since 2016.