Rename name.alias.yml to name.site.yml and drop support for group.aliases.yml

[webflo]

The docs (https://raw.githubusercontent.com/drush-ops/drush/master/examples/example.aliases.yml) have no example for a "aliases.yml". How should this fill look like? I tried the following.

stage:
  host: stage.example.com
prod:
  host: example.com

Does not work.

sites:
  stage:
    host: stage.example.com
  prod:
    host: example.com

Does not work.

sites:
  my_project:
    stage:
      host: stage.example.com
    prod:
      host: example.com

Works.

This means the resulting site-aliases are quite verbose. Because its always site+environment. I use this in combination with drupal-composer/drupal-project and never have global available site-aliases. Is it still possible to use short site aliases? example.aliases.yml has @stage as an example but i was not able to produce such an site-alias.

---

PS: I did some debugging. \Drush\SiteAlias\SiteAliasFileLoader::fetchAliasRecordFromSiteAliasData in \Drush\SiteAlias\SiteAliasFileLoader::fetchAliasRecordFromGroupAliasData returns false if the group is empty. It this the root cause? Thanks!

[greg-1-anderson]

If you do not provide an environment with your alias on the command line, then Drush 9 will default to dev, or to the first (or only) environment in the site record. Also, you may provide a root element default: that names the default environment. So @foo usually means @foo.dev.

Drush 8 (and earlier) site aliases were very loose about what sort of alias could go where. This led to a lot of variety in site alias file structure, and required Drush to do a lot of exhaustive searching. The current implementation is very opinionated about alias file structure in order to reduce the amount of searching that needs to be done. If we loosened up the rules again, Drush would need to load more files when searching for alias records.

Under the current mechanism, it is a misnomer to have an alias named @stage. Perhaps there should be some form of environment-only alias file for use only in site-specific alias records (located in __DRUPAL_ROOT__/drush/site-aliases/) so that folks can define additional environments for the current site (@self).

I recently had a conversation with @weitzman about renaming alias files to something that would be more clear. We came up with a potential name for a file that contains the environments for a single site, but did come up with names for the other variant.

New proposal:

• site-environments.yml: Only valid in a site-local context. Contains additional environments (e.g. @stage, @live for the current site @self), which can be used when the site root is identified some other way (via --root, cwd, or by calling the site-local Drush directly).
• foo.site-environments.yml: Global or site-local contexts. Contains environments for a site named "foo" (e.g. @foo.dev). Currently foo.alias.yml
• sites.yml: Usually global. Contains an alias file with a sites element containing multiple sites. Each site contains one or more environments. Currently aliases.yml.
• group.sites.yml: Usually global. Like sites.yml, but also creates a group name for the collection of aliases. Aliases may be referenced as @group.foo.dev or @foo.dev (or @group.foo or @foo for the default environment).

Maybe that's enough of an improvement to be worth the effort to make everyone rename. Thoughts?

[greg-1-anderson]

Discussed this further with @weitzman, who proposed an even simpler protocol. Below is my slightly-enhanced version of this suggestion:

1. The "groups" feature would be completely removed. Aliases of the form @group.site.env would no longer be supported.
2. All alias files must be named following the pattern name.site.yml. This file is expected to contain all of the environments (e.g. dev, stage etc.) for the site name. Neither the site name nor the site environments would be allowed to contain the character ..
3. A special alias file self.site.yml may exist in __ROOT__/drush/site-aliases (where __ROOT__ is the Drupal root or Composer root for a site identified by --root, by cwd, or by virtue of using a site-local Drush in said site's vendor directory). This alias file contains environments that may also be used for the currently-selected site.
4. Sites may only be referenced via @name.env. The shortcut @name for the dev environment would no longer be supported. The two special aliases @self and @none would still be supported.
5. The shortcut @env would be supported only under a few specific use-cases.

• If the Drupal root for a site is already identified, then @env may be used to specify an environment defined in a self.site.yml file.
• When used as a parameter, @env may also be used to identify another environment of the currently-selected site, e.g. drush @foo rsync @self:%files @live:%files would look for @foo.live (from the alias file that defined @foo) and @self.live (from self.site.yml).

This proposal would further reduce the amount of searching that Drush needed to do, at the cost of no longer supporting groups (e.g. @pantheon.site.dev).

Optionally, we could loosen #4 and assume that any @site alias that is not @self, @none or an environment per #5 is the default environment, as we currently do.

Also optionally, we could loosen #3 and allow @foo.live to search for a live environment in any self.site.yml file defined in any of the local site environments defined in foo.site.yml (presuming that file does not define the environment name being requested).

[weitzman]

This looks great to me. A couple reminders:

• example.aliases.yml needs renaming.editing
• unish.alias.yml and sut.aliases.yml need changing. I think we could get rid of one of those in a followup
• sa-convert command needs changing. also see its fixture at \Unish\siteAliasConvertTest::testSiteAliasConvert

[jurgenhaas]

I like this too, but have some further questions:

• Can we limit the number of possible directories, where those site.yml files may reside? Either ./drush or ./drush/site-aliases, but not both. If it's the latterm than site-aliases may not be the best name - instead just sites would be sufficient.
• Getting rid of the group feature sounds not bad but then I realised that this means quite a bit of extra work for hosting environments where we currently have one cron job that runs drupal's core-cron every 30 minutes for a group of sites with just a single crontab. With the groups being removed, we will have to change a lot. Or build another wrapper which resolves the group to sites and calls individual drush commands. If it's important for the Drush simplification in general, then we can live with that - but I wanted to mention that to make this a conscious decision.
• If the shortcut @name does not resolve to the default environment anymore, could that instead resolve to all environments of that site? Well, that may be the group feature coming back through the back door then ;-)

In general, I like the idea of simplifying all this. Less options is far more reliable.

[weitzman]

2. We already removed the ability fr drush to read a group aliases and run same command over them.

[weitzman]

Lets continue work at #3184

[greg-1-anderson]

Regarding @ jurgenhaas's suggestions above:

• Only ~/.drush/sites et. al. are searched now.
• As Moshe said, concurrent command execution has been removed. Use the parallel tool for this.
• @name will first attempt to resolve @self.name, if the currently-selected site has a self.site.yml file. If that does not result in a match, then @name will use the default environment for some name.site.yml file, if one exists.
• drush site-alias @name will print all of the environments for @name. This is the only place where a single identifier can be used to address multiple site environments.

[leymannx]

Here too. @greg-1-anderson what is the parallel tool? Do you have an example or a link to share?

[leymannx]

@weitzman answered it in #3019 (comment)