Text in Composer instructions

Thanks leslie, I will look at these and also ask some fellow sitebuilders.

FYI we may have download via composer functionality from the UI much sooner than we expected: https://www.drupal.org/project/project_browser/issues/3245770

I attempted to test this using Gitpod (via the button on the Project Browser project page) and during the automatic setup, I received the message:

Unable to install modules: module 'project_browser' is missing its dependency module package_manager. 
Failed to run drush en -y project_browser: exit status 1

I was able to get around this by first running ddev composer require drupal/package_manager

Then ddev drush en -y project_browser

In case any other potential testers are wondering, the "default credentials" are:

• username: admin
• password: admin

Also in the instructions above, it should be "Browse modules", not just "Browse".

Regarding the text in the modal window...

I reviewed the text with a few of our current Drupal Career Online students - their comments will be added below by each student :)

I would like to suggest the following change from this:

If you already manage your Drupal application dependencies with Composer, simply open your CLI and run the following command from the Composer root directory for your application

To this:

If you already manage Drupal application dependencies with Composer, open your command-line interface and run the following command from the project root directory for your application

Also from:

To use the module you must next install/enable it. Visit the modules page to install the module using your web browser.

To this:

To use the module it must be installed. Visit the "Extend" page using your web browser to install the module.

-mike

I suggest the first sentence reads...

Although you may download the module through the browser manually, the recommended way to download…..

I want folks to be mindful of using reductive language.

I've found an issue with the text in the "Download button" modal window:

It is in the "1. Download" section in the 5th paragraph that starts with the text "Didn't work?"
The rest of the paragraph, "Learn how to troubleshoot Composer." is blue (like a link) but isn't underlined because it isn't a link.

I'm guessing the blue decorated text should lead here:
https://www.drupal.org/docs/develop/using-composer/troubleshooting-composer

The complete 5th paragraph should then be formed like this:

Didn't work? Learn how to troubleshoot Composer.

Link fixed in https://www.drupal.org/project/project_browser/issues/3243028

We were thinking more about this (Leslie and I), that there's possibly three states in the UI for the button:

1. Download (you do not have this module on this site yet)
2. Install (you have it downloaded, but not installed/enabled)
3. Installed (already download and enabled)

For each condition, should we have different modal popups? Should the first give you composer instructions, the second give you "how to enable a module" instructions, and the third "how to remove a module" instructions? We may want to spin up child issues for this.

This issue isn't actionable at the moment. Let's also consider postponing this on #3284945: Install endpoints that leverage Package Manager + core APIs (which would mean changing the tag from MVP to 2.0)

All I would really like on this one is for someone, especially maybe a n00b or someone with fresh eyes, to read all the text we're proposing in the instructions, and make sure they make sense. I believe all this text was from the original grasmash weekend-warrior attempt, so I just want someone to review it and make sure it makes sense. If someone reviews and says "no this is all fine" then I think we close it.

Can someone help with this? Here's a current screenshot of this text:

The recommended to download any Drupal module is with Composer

That should be "the recommended way". Also, this sentence should end with a period.

I would say "terminal" or "command line" instead of "CLI", which reads like developer jargon to me.

The example command uses drupal/foo. If it's not too hard to insert the actual name of the package they're trying to install, I think that would be more useful, since it gives people a command they can just copy and paste. (Don't make me think!)

Otherwise, seems reasonable enough.

Oh, one more thing: the Drush command in the screenshot is drush pm-enable foo. Two things:

1. Is there any chance of using the real machine name of the module, rather than foo?
2. Will that command work for themes? If not, then you might want to offer the actual command (drush then is the alias; the full command escapes me at the moment) to use, so that people can copy and paste.

Oh, and a nitpick: in the explanatory text, "drush" should be "Drush", since it is a proper noun.

Also, remove the word "simply" since this is a bit ableist/can be implicitly insulting if someone finds using the command line challenging.

And there is a missing period at the end of the first sentence. :)

--with-all-dependencies is specific to Composer 2.x. Until I started working with Automatic Updates, I've been using Composer 1.x just fine with Drupal and it's possible that's true for other users. Unless Composer 2 is explicitly enforced, and I somehow circumvented the requirement, there should either be version-specific instructions, or a single version that will work on both 1 and 2.

Regarding #21: I switched back to Composer 1, and according to composer help require, there is an --update-with-all-dependencies flag. Composer 2 agrees. So maybe that should be used here?

All good suggestions! A couple clarifications:

1. the screenshot is of test content, the "Pinky and the Brain" module and all others in the tests use `foo` as the machine name. the UI definitely pulls in the correct machine name for actual projects
2. this only supports modules. If we expand to themes, we'll definitely have to account for that

Is --with-all-dependencies or variants even needed? It is not included under the modules, where this is the recommended method:

Install: $ composer require 'drupal/matomo:^1.19'

From https://www.drupal.org/project/matomo

I'll work on this

Wasn't able to make time for this and don't want to hold anyone up

I think this improvement is good enough to ship, it needs a rebase and then I think we're good to go.

Agree with removal of --with-all-dependencies as this is the `composer require` command, not `composer update` command. The option for `composer require` is --update-with-all-dependencies (-W).

The shortcuts -w|-W are the same for require and update.

Recommend against using them as they extend the scope of packages in an unknown way. Suggest using require --no-update commands when multiple modules/packages are involved followed by an update whitelisting them.

The problems reported when failing to do as requested should not be regarded as an issue. It shows the requirements for this site are more complex and need feedback from the user how to deal with them. It is unlikely that using the option provides the desired result. The command might not produce the report anymore, but that doesn't mean it produces the desired result. The user should get used to having to deal with these kind of situations, it is not exceptional !

Again, there is no algorithm to make sure the command succeeds. User decisions are needed due to circumstances. Consider taking these decisions without consulting them very bad practice.

Checked the code and tested it and it all looks good. Marking as RTBC.

Also filed this follow-up issue #3296250: machine_name field might not match the composer require namespace.

Great! Glad to see this cleaned up.