Alias documentation for Drush 9 beta7 seems to be incorrect

[jurgenhaas]

Wanted to follow the instructions in examples/example.aliases.yml but the instructions don't seem to be accurate. Here are some issues I found:

$ROOT/drush/site-aliases
$ROOT/sites/all/drush/site-aliases
$ROOT/../drush/site-aliases

Stuff in those subdirectories (site-aliases) are not recognized, they have to be in the drush directory itself to be recognized.

Put each alias in a separate file called ALIASNAME.alias.yml
Put multiple aliases in a single file called aliases.yml
Put groups of aliases into files called GROUPNAME.aliases.yml

The first one only works, when the file itself contains an alias name again which results in an alias @aliasname.aliasname instead of just @Aliasname.

The second and the third option require the root element sites: which seems redundant and I suggest to remove that.

[greg-1-anderson]

If Drush is not searching site-aliases for aliases, that is a bug. At the moment, Drush never searches into subfolders for aliases -- they must either exist directly in the search location, or directly in the search location + site-aliases.

A file called aliasname.alias.yml may contain multiple environments for the same site. You should not place aliases for unrelated sites into the same alias.yml site. The last component of an alias name should always be its environment.

We are not going to remove the sites: element from the alias groups.

[jurgenhaas]

The instruction

Put each alias in a separate file called ALIASNAME.alias.yml

sounds like one alias in such a file. No?

[greg-1-anderson]

One site, multiple environments.

[greg-1-anderson]

Maybe the point is that we should rename from ALIASNAME.alias.yml to SITENAME.site.yml.

[greg-1-anderson]

~/.drush/site-aliases works for me as a valid location to store site alias files.

[greg-1-anderson]

I was also able to successfully use:

$ROOT/drush/site-aliases
$ROOT/../drush/site-aliases

However, the later only works if $ROOT/../ is the composer root. This is not a valid location for a Drupal site that is not managed by an encapsulating Composer project.

$ROOT/sites/all/drush/site-aliases is no longer a valid location to store aliases; I removed it from the documentation.

[greg-1-anderson]

We're going to remove the group alias feature altogether, which means that the sites element is de-facto going away after all. For details, please see #3107 (comment). Feedback on that issue would be welcome.