Currently, to use file templates, users have to type in specific file names (e.g. .gitlab-ci.yml, .gitignore or LICENSE). That's fine and innocuous, but not really discoverable. The file templates feature speeds up users' workflow and it should be shown more prominently, not as an “easter egg”.
Proposal
On the New file and Edit file screens:
The New file screen always shows the template option (see designs below)
The Edit file screen only shows the template option if the file name matches a file type
Divide the current template dropdown into two dropdowns: Choose type and Apply a <type> template
Hide the Apply a <type> template by default, showing it only if:
The user has chosen a file type
Or the file name matches a file type (e.g. having a .gitignore file name should show a Apply a .gitignore template dropdown)
When choosing a template to be applied:
If the file is empty OR the user has just applied a template but has not manually modified the file's contents or name (added or removed text), the chosen template should automatically replace the file's contents and name without asking for confirmation
If the user has indeed manually modified the file's contents or name (added or removed text), an alert should be shown asking if they want to apply the chosen template (which will replace the file's contents and name) or cancel
While showing this alert, the filename and contents should be in “preview” mode, showing how the file would be if the template was applied. The file editor and the “Template” dropdowns are disabled (see image below).
Also, if the user is editing a .gitignore file (for example), the Choose type field should not be restricted to .gitignore, we only pre-select that option based on the file name to help the user.
The flow looks good. Since it only shows up for new files, it shouldn't clutter common editing. What happens if I type a filename and then pick a conflicting template type? Like I type .gitignore, then pick a .gitlab-ci.yml as the template type? Would you override my typed filename? Or would the template type field disappear or be restricted once I specify a filename?
I'm not sure about the Templates available note on the first menu. I can see that it would help advertise the feature, but it's kind of out of place and not really necessary.
Looks really good @pedroms ! seems like a pretty clear flow.
For some templates to be effective, the file names do matter. In that way I think the warning should state that the file name will or can be changed as well 😃
I suppose before accepting the template, it will just preview how the file will look? When upon cancel it will, just bring the file back to its old state?
@markpundsack The idea is to have this “Apply template” feature both for new and existing files (editing).
For dealing with filenames and file types, I think we can replace both the filename and the file content when applying a template. You will get the alert if you are editing a .gitignore file and try to apply a .gitlab-ci.yml template. We should not restrict the type field based on the filename, we only pre-select an option based on the filename to help the user.
@dimitrieh Yes, I'm going to change the alert text to reflect that the filename can also be changed.
Good idea with the preview! 💡 I'd also disable the textarea until the user chooses what he wants to do (Cancel or Apply template). I'm going to post a suggestion here.
@markpundsack Yes, maybe the “Templates available” label is too much. What do you think @tauriedavis?
Updated the alert message and added a “preview” feature. While previewing, the file editor and the “Apply template” fields are disabled (the duplicated cursor is just to indicate what is disabled).
Yes, I don't think the Templates Available label is needed. It was originally added to draw attention to something new but as we work on this more and more, I don't think we need to call it out.
@mydigitalself let me know if you have any questions/concerns and if the issue description is clear enough to proceed with development. Assigning to you 😉
@mydigitalself@pedroms I don't think this is currently as undiscoverable as "Currently, to use file templates, users have to type in specific file names (e.g. .gitlab-ci.yml, .gitignore or LICENSE)." makes it seem.
The primary way to add a file using a template is NOT by going to the "New file" page and entering a file name, but by using the links that show on every empty project:
Or in the toolbar that shows on every non-empty project:
I don't think improving the discoverability of templates should be especially high priority right now—in the end, people only use these templates once in the lifetime of a project—but if we really want to do something here, I think that this proposal would have a bigger impact: https://gitlab.com/gitlab-org/gitlab-ce/issues/19468.
@DouweM i'm not sure i entirely agree with this statement
The primary way to add a file using a template is NOT by going to the "New file" page and entering a file name, but by using the links that show on every empty project:
In fact my only experience to date with using a template was on an existing repo and my natural instinct was to go to new file, in fact I never saw the Set up CI option.
I don't think there's a huge amount of overhead to add the template option on the new file page as per the design, what I also like about the design is that it puts the template and template selector right next to each other, as opposed to the Set up CI flow where the template selector is all the way over to the right and not immediately obvious that it's related to the drop-down.
Surely this isn't a large piece of work, will bring more awareness to templates in general and makes a reasonable improvement with the affordance and visibility of the template chooser drop-down.
@DouweM we want to strongly encourage people to be making .gitlab-ci.yml files. The current way is not highly encouraging and this would go a long way. I'm with @mydigitalself that this can be a low effort / high win scenario.
Change the template dropdown to be always visible (see designs below)
@pedroms Does 'always' mean, when there's an existing template for the corresponding filename, or for literally every file? For example, do we want to display the templates dropdown when someone is editing a 5-year-old random-javascript-file.js? I ask because in such cases the utility of template selectors seems to be basically zero.
@brycepj I agree that this is not very helpful when editing a “5-year-old random-javascript-file.js”. I'm tempted to say that the template dropdown should only appear when creating a file or editing a file whose filename matches a type of template. @mydigitalself I don't see anything negative about this approach — do you?
The "Edit File" page header/navbar looks slightly different than the "New file" page. Does that have any implications for the current design?
@brycepjhttps://gitlab.com/gitlab-org/gitlab-ce/issues/29418 is certainly important and a welcomed improvement, but I don't want this issue to stall because of that. Let's focus on completing the scope of this issue and then, if we still have room, add that as a stretch goal. Does that sound reasonable to you?
If the file is empty OR the user has just applied a template but has not manually modified the file's contents or name (added or removed text), the chosen template should automatically replace the file's contents and name without asking for confirmation
@pedroms / @mydigitalself Manually modified ever or manually modified during the current session?
So, for example, when deciding whether or not to show the preview, are we checking if the committed file is the same as the template, or that the current content of the file editor is the same as the template? Or both?
I can imagine a scenario where a user applies several templates in one session without committing anything, just to see what the templates look like. Should they be asked to confirm the change each time they switch the template?
In another scenario, the most recently committed file is not different from the template used to create it. The user previews another template, and confirms it. But before committing, they change back to the template they were originally using. Should we ask them to confirm before applying?
@pedroms I'm wondering if we should indicate somehow that "Applying" a template on top of an existing file will not actually commit it. The Preview message has the tone of a warning, but really, there's not much of a risk if they apply the template and never commit it. Maybe it's not that important. I don't know. WDYT?
@mydigitalself@pedroms I'm planning on having something ready for you guys to look at today. Maybe using the UI a bit will help clarify where's best to go on this.
Out of interest, is it normal for the tab order to be, imho, a bit silly there.
Whilst testing, I noticed that tabbing from File name to what I would expect to be the content, actually tabs across to the (probably) less frequently used soft wrap and text buttons.
Just wondering that was introduced as a bug, or has always been that way. Happy to open another issue to fix in the future, or if you have time this milestone?
Out of interest, is it normal for the tab order to be, imho, a bit silly there.
Tab order is generally a problem at GitLab. I opened https://gitlab.com/gitlab-org/gitlab-ce/issues/21383 soon after I joined, but it hasn't been prioritized yet. I'm aware of at least one instance where we addressed an awkward tab order, but that's because it was on the login form.
Whilst testing, I noticed that tabbing from File name to what I would expect to be the content, actually tabs across to the (probably) less frequently used soft wrap and text buttons.
We could make tabbing skip those buttons pretty trivially.
Just wondering that was introduced as a bug, or has always been that way. Happy to open another issue to fix in the future, or if you have time this milestone?
It's always been that way, but say the word, and it's done! 😜
@mydigitalself@brycepj I agree with the undo functionality, it makes much more sense. Let's try something like the following so we can test and see if it works:
@pedroms@mydigitalself Similar to my earlier question: if we allow the user to "Undo", are the undoing the most recent change during the session, or reverting to the most recent commit?
So, if a user changes the template twice, then they click "Undo", to what do we revert?
Related, if a user applies a template for the second time, should "Template applied" and the "Undo" button temporarily flash hidden, then be showed again?
I think either way, the copy should communicate which of the two just happened.
@brycepj personally I think we can keep it very simple. at the end of the day, they are always protected by not committing the change.
Undo generally undoes the last action, in which case I think it's probably fine to revert to the last state. That means if they change it twice, then click undo, it will go back to the end of the first change.
We could briefly flash the template applied/Undo too. Although I think that given the entire body changes below, you'll know the template has been applied.
@axil thought I'd give you a heads up on this, you can now pick templates from the new file and edit file without having to type the specific template name in first.