docs about need for drush section in composer.json are incomplete

[joachim-n]

Existing document

https://www.drush.org/latest/commands/ says:

In Drush 9, the default services file, drush.services.yml, will be used in instances where there is no services section in the Drush extras of the project's composer.json file. In Drush 10, however, the services section must exist, and must name the services file to be used

What are you attempting to do

Write custom commands

In what way is the existing documentation unclear or incomplete

1. If Drush 9 is EOL, then the docs shouldn't mention it (assuming it's possible for a developer maintaining an old codebase to find the documentation for Drush 9 somewhere else)
2. The docs should say 'Drush 10 and later', as otherwise it's confusing what happens on Drush 11.
3. The docs say that on Drush >10 that the drush services file must exist. However on my project I have a custom module which has no composer.json file and only a drush.services.yml file, the project's root composer.json doesn't declare anything drush-like, the project's ROOT/drush folder contains nothing other than commented-out boilerplate, and the command is getting picked up! I have no idea how!

What should the documentation say instead?
To the best of your ability, explain what additional information would allow you to complete your task. If you already know what the documentation should say, please consider submitting a documentation pull request instead.

[weitzman]

I attempted a fix in #5249.

Missing the composer.json bits causes a notice. Use -vvv to see it. Usually the command still works tho.

[weitzman]

Please post again here or open a PR if more edits are needed.

[joachim-n]

How is command discovery meant to work in a custom module which isn't installed with Composer and so doesn't have a composer.json file?

[joachim-n]

Ah, I do get the warning you mentioned for a custom module:

[info] wsd_core should have an extra.drush.services section in its composer.json. See https://www.drush.org/latest/commands/#specifying-the-services-file. [58.39 sec, 14.

(But [info] is maybe not strong enough?)

Is Drush inspecting /DRUPALROOT/modules/custom/*/composer.json files rather than asking Composer for them?

It would be helpful if the docs said this explicitly, as my assumption was that it would go via Composer, to which custom modules are invisible.

[weitzman]

Drush does not support a site that doesnt use Composer. Hasn't for several years. Commands might happen to work for such a module but its not supported.

[joachim-n]

I think you've misunderstood me -- the site uses Composer to install Drupal and contrib modules. But we have modules in web/modules/custom/ which are our own custom code. They're not installed with Composer because they're committed to the codebase repo. Some of these modules declare Drush commands.

Should they just have a dummy composer.json consisting only of this? --

{
    "extra": {
        "drush": {
            "services": {
                "drush.services.yml": "^11"
            }
        }
    }
}

[weitzman]

Thats correct. I think a couple more keys are needed for a valid composer.json file. composer init helps with this.

[joachim-n]

I can confirm that the dummy composer as I posted above works for Drush:

 [debug] Found drush.services.yml for wsd_core Drush commands [35.18 sec, 14.83 MB]

has replaced the warning I pasted in my earlier comment.

This is not really intuitive -- it's guessable, but as a developer it leaves me thinking 'Is this REALLY the right thing to do here?'

It could really do to be documented.

[joachim-n]

Thats correct. I think a couple more keys are needed for a valid composer.json file

Drush doesn't complain, and Composer won't ever see it AFAICT, since it's not inside a Composer package.