I have noticed that the Composer-Ready Project Templates documentation inserts the -n (--no-interaction) parameter between composer and create-project.

Now, if someone searches for "composer create-project" as a string (site:drupal.org "composer create-project") they will get some hits on drupal.org, whereas if they search for site:drupal.org "composer -n create-project" they would get hits for some other pages.

It also looks like "composer -n create-project" as a string is used fairly rarely anywhere:
https://www.google.com/search?q=%22composer+create-project%22 (133.000 results)
https://www.google.com/search?q=%22composer+-n+create-project%22 (86 results)

Is it worth considering streamlining parameters to accommodate discoverability? I suggest that they be put at the end of the line, since I also think it is more reader-friendly to have the "action" commands (composer + create-project) stand side-by-side, uninterrupted by parameters like -n and -s dev, for an uninterrupted syntax like this:

tool > command > what > where + parameters

Currently
composer -n create-project drupal/recommended-project my-project
Better?
composer create-project drupal/recommended-project my-project -n

Comments

ressa created an issue. See original summary.

ressa’s picture

ressa
he/him
commented
Title: Parameters at the end in documentation, to accommodate discoverability and legibility » Parameters at the end in documentation, for better discoverability and legibility

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

ressa’s picture

ressa
he/him
commented
Issue summary: View changes
Parent issue: » #3085075: Add '-s dev' to Composer Project Template documentation so instructions work w/out a stable release

I put the parameters at the very end in my suggestion after finding #3085075: Add '-s dev' to Composer Project Template documentation so instructions work w/out a stable release, since it sounds to me like -s dev will at some point no longer be needed.

ressa’s picture

ressa
he/him
commented
Issue summary: View changes
ressa’s picture

ressa
he/him
commented
Issue summary: View changes
mmjvb’s picture

mmjvb commented

It is better to remove it completely. Should be replaced with --prefer-dist.

Do agree with documenting the options at the end of the command. Just disagree on using --no-interaction|-n when using composer interactively.

ressa’s picture

ressa
he/him
commented

Thanks for the support for putting parameters at the end of the command @mmjvb. Perhaps you could consider creating an issue under Project: Drupal core, Component: composer about the benefits of using --prefer-dist over using --no-interaction|-n?

mmjvb’s picture

mmjvb commented

The composer initiative is already aware of it.

mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented

If we ask Composer for help with create-project, it tells us this:

$ composer help create-project
Usage:
  create-project [options] [--] [<package>] [<directory>] [<version>]

So that means the docs say we should do composer create-project --option-here pack/age dir.

This fits with the desired outcome of making the docs more searchable if your search term is "composer create-project site:drupal.org".

Also, as @mmjvb points out in the docs discussion, we really shouldn’t be passing --no-interaction in the documentation anyway.

Regarding --prefer-dist, it’s true that it’s the best way to avoid a question about what to do with a .git directory, but we also currently don’t download any packages that way. It’s probably safe to say that we’ll involve one that way in the future, so let’s add it. If it’s not strictly necessary, nothing bad will happen, but if it is, then we might avoid fielding another repeat of the question about ‘it asked me what to do, how should I answer?’

Also, we should link to the docs for composer create-project.

Based on that, I'll go change the docs. :-)

mile23’s picture

mile23
Primary language English
Location Seattle, WA
commented
Status: Active » Needs review

I made these changes: https://www.drupal.org/node/2718229/revisions/view/11698350/11698505

mmjvb’s picture

mmjvb commented

In addition look at https://symfony.com/doc/current/console/input.html

# the order of options isn't important
 php bin/console app:greet Fabien --iterations=5 --yell
 php bin/console app:greet Fabien --yell --iterations=5
 php bin/console app:greet --yell --iterations=5 Fabien
ressa’s picture

ressa
he/him
commented

@mmjvb:

The composer initiative is already aware of it.

@Mile23:

Also, as @mmjvb points out in the docs discussion, we really shouldn’t be passing --no-interaction in the documentation anyway.

Sounds good to me, if you both agree that it is not good practice.

For fun I ran the create-project command without any options, which went straight through, without getting presented with a cryptic Composer "Keep/Yes/No/Always" prompt:

$ composer create-project drupal/recommended-project no-options
...
  Congratulations, you’ve installed the Drupal codebase
  from the drupal/recommended-project template!
Next steps:
....

I have created #3104445: Make Composer create-project As Lean As Possible (ALAP) to discuss options usage for this case, but also opening up for a more general discussion of applying the As Lean As Possible (ALAP) philosophy on all Composer commands, to reduce complexity.

hansfn’s picture

hansfn commented

Very happy to see that we agree on removing the -n / --no-interaction option. I hope that we can agree on removing --prefer-dist too (when -n is gone) to keep things simple.

However, I don't think we should move the options to the end. This breaks with established standards for (Unix) commands and it breaks with the syntax given by the help command as Mile23 showed in comment 10.

Using composer create-project --options-here pack/age dir will make our docs searchable enough.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

smustgrave’s picture

smustgrave commented
Status: Needs review » Needs work

Don't see any patch or MR to review.

ressa’s picture

ressa
he/him
commented
Status: Needs work » Fixed

Back in the day, the -n parameter was needed, which is mostly what this issue is about. But it is no longer needed, so I think this issue can be closed.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.