There is a number of workflow questions around Composer that need official docs.
It needs to be made clear that Composer doesn’t need to be run on a server, it can be run locally and the resulting vendor/ directory committed/upload. Previous drush make workflows need to be mapped, etc.

Jeff Geerling's blog post is a good initial overview: https://www.jeffgeerling.com/blog/2017/composer-and-drupal-are-still-str..., we start from there. The next step would be to read the two drupal.org issues: #2845379: Provide optional composer integration but don't force users to understand how to use composer and #2477789: Use composer to build sites and extract their complaints.

Once posted here, these topics can be worked on.

Current documentation

This is a list of at least some of the places where we are providing Composer documentation already so that we can remember to read/update them.

Comments

bojanz created an issue. See original summary.

ifrik’s picture

As a sitebuilder I use composer on my development site to:

  • get my Drupal core files (and then install the site with Drush)
  • get modules - including any libraries they depend on, without me being aware of that (then using drush to enable them)
  • apply patches (once I know that the patch does what I need)

On staging or production site, I use

  • composer install, to install the same versions of modules, libraries and patches that I have on my development site

Points I get confused about:

  • setting whether or not, composer updates modules to newer versions, or forcing it to install a dev version because I want a patch that has already gone in
  • not requiring a patch anymore without breaking the composer update
chrisfromredfin’s picture

  • When to use --with-dependencies (always? sometimes? what does it do? especially vis a vis updating drupal core / applying security patches, etc)
e0ipso’s picture

  • How to make composer use your local disk to fetch some dependencies using `$HOME/.composer/config.json`. Useful when you're developing and composing based on libraries that you maintain.
rfay’s picture

If drupal-project is the THING, then make that clear and explicit and promote that methodology.

* Is it the thing?
* How do you start?
* What are the robust options for maintaining a project going forward?

Mile23’s picture

@rfay: There's a lot of talk about pulling stuff from drupal-project into core, such as #2912365: Allow the drupal/drupal Composer project to apply patches

This issue (the one you're reading) can give us stuff to write documentation *about*, and also good documentation *of* pain points as all that moves forward.

eojthebrave’s picture

Issue summary: View changes

+1

Added a list of places I know we're already working on documenting Composer related things. Mostly so we can remember to update them once we have a list.

rfay’s picture

I will be at BADCamp Wed-Sat and expect to be working on learning the various ways one can manage D8 with composer. If all you composer pros would demo your methodology to me and sell me on it I'd be much appreciative. I hope to be able to contribute to documentation, or at least to consensus.

I'd love to see people list in some detail the way they're managing D8/composer right now. I guess this isn't the right issue, but I'm sure there's a right place. I recommend that people not be afraid of mentioning techniques that are not currently mentioned on d.o, like https://github.com/drupal-composer/drupal-project, which doesn't seem to be mentioned but according to @moshe is the current standard.

Mixologic’s picture

I dont think topics is the angle we should use for documentation. I think we should examine the needs of the different audiences, and let that guide us in what needs documenting.

1. End users/sitebuilders, who are building and managing a site.
2. Module maintainers hosting projects on drupal.org
3. Developers writing custom modules, or involved with more complex scenarios like dev/stage/prod and deployment patterns (what to do about -dev modules that put .git folders in your tree ? etc)
4. Distribution maintainers that are going to replace drush make with composer.

Some topics might be relevant to *all* audiences, and some people may fall into every category (e.g. most maintainers also build sites).

rfay’s picture

Please add to your excellent list core developers @mixologic - I think you're onto something good thinking about audiences rather than topics.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Mixologic’s picture

Issue tags: +Composer
bogdog400’s picture

There needs to be better documentation about updating Drupal with composer. When I try to go from 8.5.3 to 8.5.4, composer doesn't succeed. I'm told there's nothing to update.

outdated drupal/* --- returns nothing

require drupal/core:8.5.4 -- says nothing to install or update

Nothing seems to work. The documentation is spotty and it includes many statements like "try this or this, one might work."

Mile23’s picture

If you review this issue, an angel will get their wings: #2867757: Improve instructions for updating composer.json and /vendor

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.