Update User Guide for Drush 9

Thanks for posting this issue. I think you are right, we need to reconsider how to suggest the use of Drush. It cannot even be installed any more without Composer...

I recommend that we stop telling people to download core, or contrib projects using Drush. This, for now at least, is the domain of Composer. And while Drush 8.14+ might work for now, it will likely eventually be EOL as Drush 9 progresses.

So for example, on pages like this one https://www.drupal.org/docs/user_guide/en/install-prepare.html

We should replace commands like this drush dl drupal --drupal-project-rename=example with the Composer equivalent. Once you've used Composer to download the files for core, or contrib, you can still use Drush commands like drush site-install to install them. I'm pretty sure. :)

That sounds like a good plan (#5)!!

Does Drush even really work any more for installing modules and/or Drupal?

My recommendation is still using Composer to download the files, and then Drush (or Drupal console) or the UI, to enable the module.

OK. I went and looked for what we're actually recommending in the User Guide for downloads, and where. Here's an inventory:

a) install-tools https://www.drupal.org/docs/user_guide/en/install-tools.html
- We mention Drush and Composer as tools for site builders
- We mention Console as a tool for module/theme developers
- We don't tell how to install any of them, but instead say to go to the individual tool web site to install

If you go to the Drush web site, it says to install Drush 9 using Composer [the subject of this issue], and points you to https://github.com/drupal-composer/drupal-project for instructions.

And as noted here, if someone does that, they'll be using Composer for downloading/updating Drupal and modules and themes, not Drush.

b) install-prepare https://www.drupal.org/docs/user_guide/en/install-prepare.html
- Gives the drush dl command to download drupal [which won't work with Drush 9]
- Points you to the install-composer topic if you want to use Composer or Git to download drupal core

c) install-composer https://www.drupal.org/docs/user_guide/en/install-composer.html
- Gives instructions on using Composer to download the core software or modules
- Note that it says to use composer project drupal/drupal, but we should be using drupal-composer instead. See issue #2980636: Fix Composer instructions for downloading Drupal core in User Guide, or add warning for more on that.

d) extend-module-install https://www.drupal.org/docs/user_guide/en/extend-module-install.html
- Gives instructions on using drush dl to download a module, which won't work in Drush 9
- Links to install-composer topic for composer instructions

e) extend-theme -- see (d), same but for themes

So... given this, I think we should:

a) Use the patch in #2980636: Fix Composer instructions for downloading Drupal core in User Guide, or add warning, or something similar, to update the Composer instructions to use the other composer project
b) Remove instructions for downloading Drupal and modules with Drush
c) Let people use Drush 9, since that is the supported version
d) Mention that they'll need Composer if they use Drush 9
e) Probably reorganize some of these pages so they make more sense. Especially I think the "Preparing to install" page needs some help! And probably the Composer topic should be moved earlier in the outline?

Thanks for doing the work to catalog all of that Jennifer. And your proposed outlines makes sense to me. And helps address a handful of open issues for the user guide right now. So +1.

Regarding @hansfn's comment in #9 about recommending Drupal console. While I agree that Composer can be super frustrating, especially when it's not working how you would expect. My sense is that right now it is the community recommended way to manage Drupal and it's dependencies. Regardless of whether I think that's a good thing or not, I do think that the User Guide should probably try and stick to whatever the bulk of the community is doing at any given point in time. We can always adjust this in the future as that changes. Like we're doing now as Drush is no longer the best way to handle these downloads/updates. I'm totally open to being convinced otherwise though.

I guess we could mention Drupal Console as an alternative [explaining what it's an alternative to], on the Tools page, but then not give commands for doing things with it like we do with Drush throughout the guide?

Agree that there is a need for proper documentation on composer. However, consider it far too early to leave the traditional way behind. The `User Guide` should document both ways properly, without and with composer. Not everyone of the community is on board for composer to manage their site.

OK, here's a first-pass patch. I have split the install-prepare topic into several topics, and moved the install-composer topic into the Installation section (it still needs the patch from the other issue). I think this all makes more sense now...

Note: two other things to add to the list in #12: the topics on updating Core and modules and themes also say to use drush dl commands or drush upd, neither of which we support. So I took those out too.

Don't worry, we're not getting rid of the non-composer methods! Just getting rid of outdated information on Drush.

ps: I think we need another issue to add a topic on how to update core, modules, and themes if you're using Composer.

I've created a separate issue about adding information about Composer for updates: #3001626: Update Composer instructions and make sure they are linked to from other topics

And I think we need to change the title of this issue.

It looks like we should do a few things in this patch for #2969725: Add documentation about command-line quick start tool (8.6)... see latest comments there, #14-15... Or maybe finalize this and then work on the other? Not sure. Anyway, I'll think more about it on Friday -- sorry, no time until then (I'm working on building a trail bridge this week through Thursday, and pretty exhausted when I get home each evening).

I wouldn't say we are going all-in for Composer. We are still recommending downloading zip/tgz files, and Composer as an alternative to that. But Drush is still a super usefull tool to use, even without downloads... and you need Composer to get it installed these days.

I personally don't have experience with Drupal Console. Maybe I'll check it out and see ...

The current plan for this issue is to remove information about downloading stuff with Drush, and align the guide towards Drush 9.

Disagree on the direction this is going. The User Guide shouldn't remove the drush part, it is still valid, only requiring drush 8. It is missing the drupal console equivalent. It also misses the composer part and more importantly the fact you can't mix the composer way with the traditional ways.

No idea what `going all-in for Composer` means, but expect the User Guide to inform the user how to go about using composer to manage their codebase for site building. The current positioning of the tools is outdated and should reflect the current situation.

I agree we shouldn't recommend Drupal Drush 8. It is dead, outdated, and may contain security flaws, won't be updated, etc.

Using the FTP method, I agree, has flaws... but it is viable as a starting point, and even going forward if your site is simple (for instance, I personally am running several simple live Drupal 8 sites that way on shared hosting that doesn't have Composer as an option on the command line as far as I know, or at least didn't when I first installed the sites).

I hear you about Drupal Console. Sorry this is taking a while, but I will investigate Console and make a new patch.

Documenting what works is not the same as recommending!

I do not think that documenting that you can use Drush 8 is a good idea either. It may work today, but if it's not supported, we could be documenting something that opens up people to security problems.

Well, that is good to know. Won't be wasting time on the User Guide anymore.

I'm sorry you feel that way... Let me explain a bit more.

http://docs.drush.org/en/master/install/ says that Drush 8 is only supported for Drupal versions through 8.3. We are currently working on the Drupal 8.5 and/or 8.6 versions of the User Guide. To me, suggesting that people install Drush 8 and hope that it works (even though it is not supposed to for Drupal 8.4 or later) doesn't sound like a good idea. Most likely, as time goes on, they would start to run into more and more problems with Drush 8, and that would be frustrating, since we told them Drush 8 was a good option.

Because of that, it seems to me that if we are going to recommend or mention Drush, we should recommend that people use the version that is supported for the current versions of Drupal, which is Drush 9.

Does that make sense?

Sorry, we are just too far apart. Both are too convinced about their right and wrong things to do. We just disagree, so I withdraw.

See https://drupal.stackexchange.com/questions/231741/has-drupal-abandoned-d...
If only the User Guide was the resource people needed!

I took a quick look at the Drupal Console documentation. A few thoughts:

a) According to the documentation, it looks like to install Drupal Console, you need to install both the "Launcher" (to run global Console commands), and Console itself (within each Drupal installation, to run installation-specific Drupal commands). Reference:
https://docs.drupalconsole.com/en/getting/project.html

b) The launcher install instructions assume that you already have curl and PHP installed, but there aren't requirements pages that explain this. I think they would be confusing instructions for people maybe less familiar with the command line, and they would probably not work on all computers.
https://docs.drupalconsole.com/en/getting/launcher.html

c) The Console instructions say it needs to be installed using Composer.
https://docs.drupalconsole.com/en/getting/composer.html

d) Given that you apparently need Composer to do anything with Console, I don't see it being that much of a big win over just using the Composer instructions to download Drupal and modules. And I don't think it has much to offer for commands other than the downloading commands.

So... I think for now we should stick with Composer for downloading. But I'm going to make a separate issue where we can explore whether to add more about Console to the User Guide (it will mark this one as Related, so see sidebar).

OK...

So, we now have related issues for:
- Drupal Console - #3005751: Add information about using Drupal Console to User Guide
- Quick start tool - #2969725: Add documentation about command-line quick start tool (8.6)
- Fixing up Composer docs - #2980636: Fix Composer instructions for downloading Drupal core in User Guide, or add warning

Let's leave those related tasks to those related issues. Given that, I think the patch in #17 should be reviewed as it is, so setting this back to Needs Review. I'll go look at the Composer docs patch now too, because that urgently needs to get done.

Drupal Console has a lot more than downloading as far as commands go - *roughly* equivalent to Drush in features, although both have at times things the other doesn't and there are lots of differences. By default, the Drupal Commerce composer starter installs Drupal Console and not Drush, the Drupal Composer Project starter from Github installs both. /clarification of dubious necessity.

Looks awesome Jennifer. Did have 1 typo and 1 minor concern.
+1 RTBC except for that minor concern.

diff --git a/source/en/install-composer.txt b/source/en/install-composer.txt
index 2637bd5..440ccb2 100644
--- a/source/en/install-composer.txt
+++ b/source/en/install-composer.txt
@@ -34,13 +34,13 @@ development server or your live site. See <<install-tools>>.
 
 ==== Steps
 
-If you are unable to install the Git or Composer tools on your live server,
-after following the steps in any of the sections below on your local server, you
-will need to transfer any updated or added files to your live server. The
-recommended procedure is to make an archive or zip file of the new and changed
-files, transfer the archive to your live server, and extract it there. If you
-are using Composer, make sure to check for updates and additions to the
-following files, in the root of your installation:
+If you are unable to install the Git or Composer tools on your live server, you
+can follow the steps in any of the sections below on your local server, and then
+transfer any updated or added files to your live server. The recommended
+procedure is to make an archive or zip file of the new and changed files,
+transfer the archive to your live server, and extract it there. If you are using
+Composer, make sure to check for updates and additions to the following files,
+in the root of your installation:

I'm concerned here about one thing... deleted files. In some cases, not deleting files will be harmless, but in others 💣.
Maybe something like: [snip]The recommended procedure is to make an archive or zip file of the new/changed folders, transfer the archive to your live server, and extract it there after deleting changed folders.
(also, ook argh that is a dangerous life to live, but good to provide instructions for those hamstrung by their hosting providers)

 a/source/en/install-prepare.txt
+drush site-install standard --db-url='mysql://DB_USER:DB_PASS@localhost/DB_NAME' --site- name=example

The example drush si command has an extraneous space in --site-name.

RE #34 -- let's leave the discussion about what to say for Console to #3005751: Add information about using Drupal Console to User Guide.

RE #35 -- making a new patch to address review, thanks! The new paragraph in install-composer says (sorry, interdiff failed me here):

If you are unable to install the Git or Composer tools on your live server, you
can follow the steps in any of the sections below on your local server, and then
transfer any updated or added files to your live server. The recommended
procedure is to make an archive or zip file of the new and changed folders,
transfer the archive to your live server, delete the folders that have changed,
and extract the archive. If you are using Composer, make sure to check for
updates and additions to the following files, in the root of your installation:

I use know interdiff way less than I should and like it less than it deserves ;)
Looks good to me and for unfamiliar users I think it is sufficiently clear.

Read through the entire patch. Looks good to me. +1 RTBC.

This looks good to me. I have just one small nit-pick below. Overall, I like the decision to split this into multiple pages. I think it helps reduce duplication and removes some of the "if this then that" confusion that arises from trying to cover to many things on a single page.

+++ b/source/en/install-decide.txt
@@ -0,0 +1,67 @@
+Use Git::
+  It is possible to download a development version of the core files using Git,
+  although you will then need to use Composer to download additional
+  libraries. See <<install-composer>> for instructions.
+
+Download manually from the web site::
+  You can download the core software, or a distribution that contains the core
+  software and additional modules or themes, from the web site. See
+  <<install-manual>> for instructions.

Can we change the order of these two. I don't think we're necessarily trying to recommend one approach over the other but since people might take it that way I would order them as:

- Composer
- Download manually
- Git

Both composer and manually download also imply that you're getting a tagged release. Which is probably better in most cases.

I like @eojthebrave's suggestion in #40.

It looks like we're probably going to eliminate Git, as a downloading method, from the User Guide -- see #3007090: Remove Git as way to download core/modules/themes. But for now, yes I'll change the order.

Adding a follow-up issue also: #3007656: Update lists of topics to current list

OK, I changed the order of those two paragraphs as in #40, and otherwise committed the patch in #37. Oh, I noticed we used the word "folder" instead of "directory" in the Git/Composer topic, so I fixed that as well (our standard is to use "directory" to refer to directories/folders).

Thanks for all the discussions and reviews! I'll be sending an email message to the translation group...