Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change(v2): swap init parameter order for name and template #1720

Closed
wants to merge 2 commits into from

Conversation

@wgao19
Copy link
Collaborator

commented Jul 29, 2019

Motivation

Swap init command order for template and project name.

Previously our init command was

$ init [name] [template]

So in the doc we exemplify as

$ npx @docusaurus/init@next init my-website classic

This is not too bad. But we also accept git url for template, in which case the template argument will be very long and people will nearly certainly copy and paste.

$ npx @docusaurus/init@next init [name] https://github.com/wgao19/docusaurus-template-no-style.git

Then having template as the last argument is not as friendly as having it before the project name because people can copy and paste the whole thing and input a project name.

$ npx @docusaurus/init@next init https://github.com/wgao19/docusaurus-template-no-style.git [name]

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

(Write your test plan here. If you changed any code, please provide us with clear instructions on how you verified your changes work. Bonus points for screenshots and videos!)

NA

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

@wgao19 wgao19 requested a review from endiliey Jul 29, 2019

@wgao19 wgao19 requested a review from yangshun as a code owner Jul 29, 2019

@docusaurus-bot

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

Deploy preview for docusaurus-2 ready!

Built with commit 7488037

https://deploy-preview-1720--docusaurus-2.netlify.com

@docusaurus-bot

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

Deploy preview for docusaurus-preview ready!

Built with commit 7488037

https://deploy-preview-1720--docusaurus-preview.netlify.com

@yangshun
Copy link
Member

left a comment

Hmm I'm not so sure whether it's a good idea to change the order now. But if we were to change it, we should do it asap. There's also value in doing it in a similar fashion as Gatsby: https://www.gatsbyjs.org/docs/starters/

Alternatively, make some of the parameters into options so that the order wouldn't matter, we can default the template to our classic template.

Will defer to @endiliey to make the call.

@endiliey

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

if we merge this now, need to make sure we release new alpha otherwise the order is wrong for certain version.

id prefer we do a revamp once and for all though. agree on defaulting it to classic template

@endiliey
Copy link
Collaborator

left a comment

actually tbh i feel there isnt a lot of benefit of changing the order now.

in fact: it broke the order for previous version (some people can just remove the @next and later find that the order is different for previous version

and also if both options are not passed, we still prompt for name first and then template.

im thinking to maybe lets just revamp the init once and for all

simplify it to

npx @docusaurus/init then interactively prompt ?? or default the name and template to website and classic

thoughts ?

@yangshun

This comment has been minimized.

Copy link
Member

commented Jul 29, 2019

I agree with Endi's suggestions.

@wgao19

This comment has been minimized.

Copy link
Collaborator Author

commented Jul 29, 2019

and also if both options are not passed, we still prompt for name first and then template.

I agree with this, please keep this behavior. But please do not remove the default CLI command argument option. The brevity of just one copy and paste and be done with it is unparalleled.

Let me rephrase properly what I mean regarding the benefit of swapping the order:

Currently, we instruct people to initialize project like this

npx @docusaurus/init@next init [template] [name]

This is OK since they're both optional and the template classic is quite short and easy to type.

However, if we want to promote initializing projects from git repo, the behavior becomes:

npx @docusaurus/init@next init [your project] https://github.com/very-long/git-name-no-one-is-typing

People cannot copy and paste this string directly because there is a [your project] in the middle.

Then they'd have to copy the first section

npx @docusaurus/init@next init 

Then type their project name or whatever,

[my project]

then copy and paste the git repo

https://github.com/very-long/git-name-no-one-is-typing

I think the "a lot of benefit" is rather subjective.. it's whether we want to promote the behavior of using repo as template. If we do want that, the difference is very non trivial. Just try it, you copy and paste twice, tab in and out of your terminal, it's ridiculous.

Gatsby's command takes URL in middle doesn't mean it's the best experience.

However, I'm OK with closing this issue because currently both of you are against it. And I'm not very familiar with CLI development so I think I'm not the best person to make the call. I'll thereby close this issue to let you guys plan things properly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
5 participants
You can’t perform that action at this time.