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.
- https://www.drupal.org/docs/user_guide/en/install-tools.html - Overview of what composer is, from the User Guide
- https://www.drupal.org/docs/user_guide/en/install-composer.html - Using Composer to download files, from the User Guide.
- https://www.drupal.org/docs/develop/using-composer - This guide contains various pages documenting using composer for various tasks and is likely the place that most people are going to find information
Comments
Comment #2
ifrikAs a sitebuilder I use composer on my development site to:
On staging or production site, I use
Points I get confused about:
Comment #3
chrisfromredfinComment #4
e0ipsoComment #5
rfayIf 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?
Comment #6
Mile23@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.
Comment #7
eojthebrave+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.
Comment #8
rfayI 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.
Comment #9
MixologicI 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).
Comment #10
rfayPlease add to your excellent list core developers @mixologic - I think you're onto something good thinking about audiences rather than topics.
Comment #12
MixologicComment #13
bogdog400 CreditAttribution: bogdog400 commentedThere 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."
Comment #14
Mile23If you review this issue, an angel will get their wings: #2867757: Improve instructions for updating composer.json and /vendor