Add intro message

[lhupfeldt]

trafficstars

I would like a clean way to display an intro message before the input questions. Right now I'm doing this by adding it to the first question. There are a couple og potentional problems with this:

• An argument gets added before the first argument, causing the intro message to be display after the first question
• It is not possible to programmatically use the intro message, e.g. for a UI.

I suggest adding an intro_message configuration item. Or maybe pre_message, post_success_message, post_fail_message?

[yajo]

Seems legit.

Is the finish message really needed, or just a "by the way"?

post_fail_message?

I don't think so. #398 is regarding validation, with a better UX. Apart from that, we should simply not fail. And if something fails, the exception message should be most useful IMHO.

[pawamoy]

Side note: I've succesfully added a post-generation message ("thank you for using our template blablabla") using a task 🙂

[lhupfeldt]

Is the finish message really needed, or just a "by the way"?

The finish messages were "by the way" :)

[lhupfeldt]

And I agree that an exception should not be hidden, so a post message should not be a replacement for the exception message/stacktrace. The nice thing about declared post message vs printing from a task would be easy UI integration. But I guess it could be added later if someone need it.

[sisp]

How about the following extension to copier.yml?

• For plain text:

  _message: "Project {{ project_name }} successully created! 🎉"
  

• For inline Markdown (we could use rich to render it in the terminal :heart_eyes:):

  _message: |
    # Next steps
  
    Project {{ project_name }} successfully generated! 🎉
  
    This is what you should do next:
  
    1. ...
    2. ...
  

• For including an external file (plain text or Markdown), we can use a Jinja include:

  _message: "{% include 'path/to/message.md.jinja' %}"
  

In fact, I suggest to always treat the message as Markdown and render it. When it's "plain text", there is no difference.

We should distinguish between a post-copy and a post-update message. This could be achieved through a new Jinja variable such as _copier_conf.action: Literal["copy", "update"]. For instance:

_message: "Project {{ project_name }} successully {{ _copier_conf.action == 'copy' | ternary('created', 'updated') }}! 🎉"

WDYT, @copier-org/maintainers and @lhupfeldt?

[pawamoy]

Note that when updating, the copy message might be displayed before the update one, and not instead of, though that's coming from tasks, so maybe a tighter integration can take better care of that.

Other than that I like your suggestions @sisp :slightly_smiling_face: _message here though is only for post-copy/update, right? What about the intro message originally asked in this ticket?

[sisp]

Note that when updating, the copy message might be displayed before the update one, and not instead of, though that's coming from tasks, so maybe a tighter integration can take better care of that.

I'm not sure I understand what you mean. :thinking: Are you referring to a message printed by a task?

Other than that I like your suggestions @sisp slightly_smiling_face _message here though is only for post-copy/update, right? What about the intro message originally asked in this ticket?

Yes, it's only for post-copy/update. I hadn't noticed that the original question was about a message before the first question gets asked :facepalm: as much of the discussion later was about a finish message. Now that I do, I wonder about the value of an intro message. :thinking: Unless Copier pauses and the user needs to press some button to continue, would anybody actually notice an intro message (unless it's huge)?

My use case is to print next steps instructions after successful project creation/updating that depend on the answers of some of the questions.

[pawamoy]

I'm not sure I understand what you mean. thinking Are you referring to a message printed by a task?

Yes. When updating a project, tasks run for the previously used version of the template, when a fresh copy is regenerated, as well as when the new version of the template is used to update the project in-place. In short, tasks run two times (but only once in the current project).

What I meant by "tighter integration" is that if _message is natively supported, we can have parameters in the right places to say "don't print the message in the copy part of the update process".

Now that I do, I wonder about the value of an intro message.

I guess it's just a way to introduce some concepts/questions to the user, within their console. Template writers have no other way to write things to the console before asking questions (they surely don't want to provide a Copier wrapper that echoes something before running copier copy). The intro message could be templated and use Jinja extensions to use system info like the username.

---

$ copier copy template output
Hello USER, thanks for generating a project using TEMPLATE.
We will ask a series of question. to which you have to answer.
Typing enter without text will use the default value, if any.
Default values will be shown in-between square brackets (`[default]`).
For boolean questions, the capital letter is the default value (`[Yn]` for yes, `[yN]` for no).

project_name?
...

[sisp]

Thanks for the clarification! :+1: Yes, a tighter integration should be able to control the printing better.

There's actually another point about message printing. Should the -q, --quiet flag suppress those messages?

Thanks for the intro message example, I see how this might be useful now. :+1: How about supporting both intro and post-copy/update messages in the same way? Here are a few ideas for new syntax:

_message:
  start: ...
  finish: ...

_message:
  start: ...
  end: ...

_message:
  opening: ...
  closing: ...

_message:
  introduction: ...
  conclusion: ...

_message:
  preface: ...
  postface: ...

_message:
  preamble: ...
  end: ...

_message:
  prolog: ...
  epilog: ...

_message:
  welcome: ...
  goodbye: ...

_message:
  hello: ...
  bye: ...

[pawamoy]

I think I like preamble/end the most :slightly_smiling_face: I'm also attracted to prolog/epilog because the words have the same length :sweat_smile: but they feel less appropriate in Copier's context.

[yajo]

We can have 4 to cover all scenarios:

_message_before_copy: Hello, welcome...
_message_after_copy: I hope you liked it. Now do this and that
_message_before_update: It looks like you're updating. Beware, this version includes a breaking change. Blah blah.
_message_after_update: Done, friend. Now pay me 1 million dollars or run `git reset --hard`

If you add it like this, just with _message_before_copy we're done fixing this issue; but you'd leave room for others to come later.

BTW, splitting into different configs might look ugly, but makes usage of !include more capable.

[lhupfeldt]

Yes, it's only for post-copy/update. I hadn't noticed that the original question was about a message before the first question gets asked facepalm as much of the discussion later was about a finish message. Now that I do, I wonder about the value of an intro message. thinking Unless Copier pauses and the user needs to press some button to continue, would anybody actually notice an intro message (unless it's huge)?

There is no need for an extra pause. Copier pauses on the first question and the intro messages is displayed beffore that and thus visible. I really mostly care about a message before the first question.

I think maybe _message should be general, allowed anywhere, with the obvious restriction that it may only reference variables previously defined (also see #1205, #1204, #1203 concerning temporary varaiables). Then when: _update, when: _copy, when: something-else could be used to toggle messages.

[lhupfeldt]

On the other hand a completely general messages allowing jinja interpolation might make it more difficult to do potential GUI (web page) intgration.