On #2950307: Update User Guide for Drush 9 we are removing information on how to update modules, themes, and Core using Drush, since that no longer works in Drush 9 (at least, I think it doesn't) -- you're supposed to use Composer for getting the code updated.

We need to make sure the information about using Composer to download/update core and contrib is correct [stop using no-dev options, as it is non-standard within the Drupal project, and it doesn't work well with updates, for one thing!].

We also need to make sure that the Composer topic page is linked to from elsewhere (such as the pages on how to update/download modules and update core), and has an appropriate title that includes the words "update" and "download".

Also, we need to include some extra information about the command options. See #3022675: clarify what "dev" means in the composer installation instructions, marked as a duplicate of this issue.

CommentFileSizeAuthor
#26 3001626-v3.patch10.27 KBjhodgdon
#21 3001626-v2.patch10.28 KBjhodgdon
#16 3001626.patch10.28 KBjhodgdon
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon created an issue. See original summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: Add information on updating Core, modules, themes using Composer » Link to information on updating Core, modules, themes using Composer
Status: Active » Postponed

Actually, this information is in the install-composer topic. But:
- The title of this topic doesn't say anything about updating
- When we talk about updating modules/themes/core, we don't reference this topic.

So, we need to fix these two problems. Probably postpone until after #2950307: Update User Guide for Drush 9 and #2980636: Fix Composer instructions for downloading Drupal core in User Guide, or add warning are fixed.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Postponed » Active

Time to work on this one!

Note: Current section on updating in the install-composer.txt file says this:

===== Using Composer to update a project's files

Follow these steps to update the files for the core software or a contributed
module or theme, after having already started to manage dependencies with
Composer:

. Determine the short name of the project you want to update. For the core
software, it is _core_. For contributed modules and themes, it is the last
part of the URL of the project page; for example, the Geofield module, at
https://www.drupal.org/project/geofield, has short name +geofield+.

. If you want to update to the latest stable release, use the following
command, substituting the short name of the project to be updated for
+geofield+:
+
----
composer update drupal/geofield  --with-dependencies
----

. If you need a specific version, determine how to enter the version number you
want to update to. For example, for version 8.x-1.7 of a contributed module, you
would enter just the 1.7, and for the core software version 8.3.1, you would
enter 8.3.1. Then enter the following command at the root of your site
(substituting the short name of the project for +geofield+ and the correct
version number):
+
----
composer require drupal/geofield:1.7
----
ressa’s picture

ressa CreditAttribution: ressa at Ardea commented

@Mixologic recommended downloading Drupal 8 with Composer in #2980636: Fix Composer instructions for downloading Drupal core in User Guide, or add warning (#29) with this command:

composer create-project drupal-composer/drupal-project:8.x-dev mydir --no-dev --no-progress --stability dev --no-interaction

... which has now been added to the User Guide. So perhaps the update part of the User Guide could be something like this?

===== Using Composer to update a project's files

Follow these steps to update the files for the core software or a contributed
module or theme, after having already started to manage dependencies with
Composer:

====== Update Drupal core

If you want to update to the latest stable release of Drupal core, use
the following command:
----
composer update drupal/core --with-dependencies --no-dev --no-progress --stability dev --no-interaction
----

====== Update a module or theme

. Determine the short name of the project you want to update. For contributed
modules and themes, it is the last part of the URL of the project page;
for example, the Geofield module, at
https://www.drupal.org/project/geofield, has short name +geofield+.

. If you want to update to the latest stable release, use the following
command, substituting the short name of the project to be updated for
+geofield+:
+
----
composer update drupal/geofield --with-dependencies
----

. If you need a specific version, determine how to enter the version number you
want to update to. For example, for version 8.x-1.7 of a contributed module, you
would enter just the 1.7. Then enter the following command at the root of your site (substituting the short name of the project for +geofield+ and the correct
version number):
+
----
composer require drupal/geofield:1.7
----

According to the community run documentation page Update core via Composer you need to use webflo/drupal-core-require-dev, is this still true?

Also,

If you are upgrading from 8.5 to 8.6, you need to replace "~8.5.x" with "^8.6.0" for drupal/core and webflo/drupal-core-require-dev in composer.json.

If this is still necessary, to upgrade from 8.6 to 8.7, that should also be stated explicitly.

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented

The community documentation is a result of hard-work and a lot of discussion, and I have been heavily involved. The last section about "composer prohibits" maybe should be added to the user guide - not sure - but I don't think we should link to that page. The user guide should be self contained when it comes to basic composer usage.

Unfortunately "webflo/drupal-core-require-dev" is required even if we install Drupal using Composer create-project using "--no-dev". (It's actually not clear to me why, and composer "composer prohibits" doesn't report a problem. Weird. I tested several times.) So the the correct (matching) update command is:

composer update drupal/core webflo/drupal-core-require-dev --with-dependencies --no-dev --no-progress --no-interaction

(Stability makes no sense for the update command - only for the create-project command.)

We should ask ourselves if the "--no-dev" thing is worth it. Running the update command once without "--no-dev" and the benefit (of less installed packages) is gone. Remember that we use the update command a lot - not just for core updates. And https://github.com/drupal-composer/drupal-project doesn't use it ... I'm thinking that we can skip "--no-progress" too. And "--no-interaction" as there normally isn't any interaction to skip. Then we end up with

composer update drupal/core webflo/drupal-core-require-dev --with-dependencies

PS! The comment about editing composer.json for 8.5 to 8.6 is only relevant for that upgrade - not for 8.6 to 8.7. This bug has been fixed in drupal-composer/drupal-project, and we can skip that comment it in the User Guide IMHO.

ressa’s picture

ressa CreditAttribution: ressa at Ardea commented

Thanks for thorough feedback @hansfn.

The last section about "composer prohibits" maybe should be added to the user guide

I agree, it is quite useful

... but I don't think we should link to that page. The user guide should be self contained when it comes to basic composer usage.

Again, I agree. Should we also include the steps under Stepwise update instructions as well then?

We should ask ourselves if the "--no-dev" thing is worth it. Running the update command once without "--no-dev" and the benefit (of less installed packages) is gone.

I think we should be consistent, and if we recommend to download with --no-dev, we should also update with --no-dev. Also, if and when --no-dev is not included, Composer will start to download the 41 developer packages, a possible cause for confusion.

PS! The comment about editing composer.json for 8.5 to 8.6 is only relevant for that upgrade - not for 8.6 to 8.7. This bug has been fixed in drupal-composer/drupal-project, and we can skip that comment it in the User Guide IMHO.

Good news, that makes the update process simpler.

By the way, do you know and can share the commands to test updating from one Drupal core version (fx 8.6 to 8.7) with Composer? This could also be quite useful for users, if they want to acquaint themselves with the update process and be better prepared, for example before an important security release, where little "bumps in the road" can cause concern.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Version: 8.x-5.x-dev » 8.x-6.x-dev
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Related issues: +#3024030: add --update-no-dev to "composer require" instructions, +#3022675: clarify what "dev" means in the composer installation instructions

Adding some related issues that could use a look from @ressa and/or @hansfn, thanks!

ressa’s picture

ressa CreditAttribution: ressa at Ardea commented
Status: Active » Needs review

Here is a new suggestion for the part about updating Drupal core with Composer, based on recommendation by @hansfn. Since we are omitting dev-packages when downloading modules (composer require --update-no-dev drupal/geofield, see #3024030: add --update-no-dev to "composer require" instructions), I have added --no-dev here.

====== Update Drupal core

If you want to update to the latest stable release of Drupal core, use
the following command:
----
composer update drupal/core webflo/drupal-core-require-dev --with-dependencies --no-dev
----
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Hm. This webflo thing...
https://github.com/webflo/drupal-core-require-dev
The README there says it provides the dev packages of Drupal Core as a stand-alone package.

So if we do an update and add that in, then we're getting those dev packages, even though we didn't initially want them.

Also, on
https://github.com/drupal-composer/drupal-project#updating-drupal-core
it says to update Core we need to do:

composer update drupal/core webflo/drupal-core-require-dev symfony/* --with-dependencies

But this command assumes that we did a composer create-project without the --no-dev option.

So... It all seems wrong. Either we should take out the --no-dev option (because it is ultimately impossible to use Composer without the dev stuff), or we should not need the webflow dev project.

So. ... I would like to test this, but it seems like I cannot specify a particular version of Drupal to download when I do a create-project with drupal-composer/drupal-project. I tried putting 8.6.0 into the command (with the intention of updating to 8.6.5 later), but it's interpreted as the version for the drupal-composer project itself, not Drupal. ???

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented

As I commented in the "--update-no-dev" issue, I think it will be difficult / counterproductive if the User Guide is recommending something different than "the rest of world" - being the community docs, the official template docs are just normal usage of commands.

Anyway, to install a specific version of Drupal core with the Composer template, first run composer create-project with the "--no-install" option. Then edit the composer.json file so it requires exactly the version of drupal/core that you want. Then run composer install. Finally, edit composer.json again relaxing the Drupal version requirement - allowing for updates with Composer.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Title: Link to information on updating Core, modules, themes using Composer » Update Composer instructions and make sure they are linked to from other topics
Issue summary: View changes

I see your point on the "no-dev" thing, and closed the other issue.

So, we need a new patch here that removes the no-dev stuff. Updating title.

jhodgdon credited alex.a.

jhodgdon credited mmjvb.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Let's also make sure we include #3022675: clarify what "dev" means in the composer installation instructions.

Also, crediting everyone who worked on the other issues.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
FileSize
3001626.patch10.28 KB

Here's a patch. Commands now match what are on
https://www.drupal.org/docs/develop/using-composer/using-composer-to-man...
https://www.drupal.org/docs/8/update/update-core-via-composer

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

This all looks good to me. I like the addition of links to existing module and theme topics to the Composer instructions. I like the consolidation of composer commands. I also agree with the decision to remove the use of --no-dev especially on the basis of the User Guide should be documenting what the community is recommending as a best practice. The new text reads fine and matches our standards. So, +1 from me.

I do think it would be great to have someone else who has done more of the legwork in this issue, and those closed as duplicates of this, also review the content.

Thanks to everyone who has been involved in taking the time to deeply understand all the technicalities of this stuff so that the rest of us can just read the instructions and cross our fingers. :)

mmjvb’s picture

mmjvb CreditAttribution: mmjvb as a volunteer commented

It still mentions --stability dev which means poor understanding on version constraints. Considering that a discrete version is mentioned the --stability dev is redundant.

When keeping this in the documentation please remove my credit.

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented

I assume the reason --stability dev still is mentioned, is that it's part of the actual installation instructions on https://github.com/drupal-composer/drupal-project

I agree that it seems redundant / shows lack of understanding, so I created an issue - trying to solve it at the source first: https://github.com/drupal-composer/drupal-project/issues/449

Will review the patch later.

mmjvb’s picture

mmjvb CreditAttribution: mmjvb as a volunteer commented

-===== Using Composer to update a project's files
+===== Using Composer to updated previously-downloaded files

Doesn't sound right: should stay update

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
FileSize
3001626-v2.patch10.28 KB

Thanks for the reviews! #20 is correct; here's a new patch that fixes it. (no other changes)

Regarding --stability dev... it looks like we need to keep it for now. But I'm not sure what you mean in #18 about "Considering that a discrete version is mentioned the --stability dev is redundant.". What discrete version is mentioned in the create-project command?

Also to clarify @mmjvb -- are you saying that do you want me to not give you issue credit here? You've helped move these related issues forward, so normally I would grant issue credit to anyone who has done so on any issue, and only update the "Attribution" lines in the User Guide if someone contributed a substantial amount of text to the writing of the Guide. (No attribution updates are in this patch.)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Oh, I understand what you mean about --stability dev. Doh! Anyway, let's wait and see what happens with https://github.com/drupal-composer/drupal-project/issues/449

mmjvb’s picture

mmjvb CreditAttribution: mmjvb as a volunteer commented

In the other topic I explained the usage of --stability dev being redundant when using drupal-composer/drupal-project:8.x-dev. When that is ignored, I want no credit. Not sure I understand why this is depending on #449 in drupal-composer/drupal-project.

When nothing of my advice makes it to the documentation, you can leave out the credit as well.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

OK, I understand.

So... just to explain... in the User Guide we are trying to document the standard, accepted practice in the form of a tutorial -- not create new practices. If the developers of the drupal-composer/drupal-project composer endpoint say in their documentation that we should use --stability dev when creating the project, and if the drupal.org documentation has also adopted that, then until those sources change, the User Guide will probably not try to create new standards and go against that source documentation.

This is why @hansfn's issue in the composer endpoint project is the right way to go. Maybe they have a reason for --stability dev, I don't know. If they don't, they (and we) should stop using it. But until then, the Drupal community has apparently adopted this as the right command to start the project (from the developer), so we will put that into the User Guide. If it didn't work for some reason, we would definitely want to remove it, but if it works and the documentation we're relying on says to use it, we don't want to have a different standard in the User Guide.

For the same reason, we're not doing --no-dev any more in the User Guide, as discussed above.

Thanks for bringing this up though. Let's see what the composer endpoint project developers say. And we can also hope that Drupal Core figures out something better than having to use this particular composer endpoint eventually too (they are working on it)... At which point, we'll need to come back and update the User Guide again.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Taking care of issue credit request.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
FileSize
3001626-v3.patch10.27 KB

The maintainers of the GitHub composer endpoint have removed --stability dev from their site via issue
https://github.com/drupal-composer/drupal-project/issues/449

So, we should now remove this here. New patch. Only difference is the initial composer command line, which is now:

composer create-project drupal-composer/drupal-project:8.x-dev mydir --no-interaction

Reviews welcome!

@mmjvb -- want your issue credit back again? :)

mmjvb’s picture

mmjvb CreditAttribution: mmjvb as a volunteer commented

Yes, looks deserved now!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Great -- thanks for your patience as we "dot all the i's and cross all the t's" and make sure we're fairly representing the community's opinion of best practices.

mmjvb’s picture

mmjvb CreditAttribution: mmjvb as a volunteer commented

See https://www.drupal.org/project/webmasters/issues/3024621 for my motivation in this matter.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I just created a new issue about Composer in the User Guide -- to do (if we decide to) after this one:
#3029769: Add instructions for converting tarball download to Composer
Thoughts/ideas welcome there!

We still need a final review here too. Thanks!

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented
Status: Needs review » Reviewed & tested by the community

Patch looks fine.

  • eojthebrave committed ed04d29 on 8.x-6.x authored by jhodgdon 
    Issue #3001626 by jhodgdon, mmjvb, hansfn, ressa, eojthebrave, alex.a:...
eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented
Status: Reviewed & tested by the community » Fixed

Thanks everyone for seeing this through, and taking the time to help make sure we get it right. I've committed the patch in #26 to the 8.x-6.x branch. I didn't change any of the issue credits from what @jhodgdon had them set at already.

We should probably notify the translation teams since this changes a bunch of existing files. I'll take care of doing that right now.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

auxiliaryjoel’s picture

auxiliaryjoel CreditAttribution: auxiliaryjoel commented

I have to admit reading through all these commits made my brain melt a little bit and I'm still not 100% certain what it all means!

So I'm wondering if someone can confirm if I use this:
composer create-project drupal-composer/drupal-project:8.x-dev mydirectory --stability dev --no-interaction

Am I getting a fully functioning drupal install?

I am using it on localhost MAMP build to create/test site before deployment onto live shared cpanel server.
I won't be using composer on the shared server, I will instead keep the site running/up to date via composer on my localhost, and push with git to shared server (a.k.a. the live/public view).

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented

Hi, auxiliaryjoel! I'm not sure why you are reading this issue instead of the actual User Guide? And please don't post you question in multiple locations, it just creates extra work - to read and maybe answer it twice.

Please read https://www.drupal.org/docs/user_guide/en/install-composer.html If the instructions aren't clear, open an issue with suggested improvements. (Your command or the similar command in the User guide will give you a functional Drupal installation.)

auxiliaryjoel’s picture

auxiliaryjoel CreditAttribution: auxiliaryjoel commented

Sorry for posting in multiple locations.
I noticed one thread was closed after I posted, so posted 2 a second.
I read the user guide but it was vague. As I didn't have the answered, I didn't want to suggest anything as I didn't know what to suggest (if that makes sense)
I tried many forums on drupal.org, drupal answers, stack exchange, etc. and could not find a definitive answer so apologies I just was not sure where else to post such a question.

hansfn’s picture

hansfn CreditAttribution: hansfn as a volunteer commented

Both the User Guide as mentioned and the community docs clearly states the recommended Composer command. However, there are probably many forum posts, blog posts and so that mention other options. You could of course just have gone to the source of the command. Anyway, I hope you feel confident about using the recommended Composer command now :-)

auxiliaryjoel’s picture

auxiliaryjoel CreditAttribution: auxiliaryjoel commented

Thanks hansfn