Document differences between drupal-project and drupal/recommended-project

[danepowell]

I think any lay person (or even a rather experienced contributor like myself) could be mighty confused at the existence of multiple "official" project templates, namely https://github.com/drupal-composer/drupal-project and https://github.com/drupal/recommended-project

The least we can do is to acknowledge that multiple options exist, and the high level differences between them so users can make an informed choice.

Consider this an alternative to #550

[webflo]

Could you please rephrase this sentence and avoid using "more"? IMO, both projects are equally good. If one is better than the other this is up to reader.

How about?

This project (drupal-composer/drupal-project) predates drupal/recommended-project and has its own documentation, own functionality (such as Drush out of the box), and community support.

Or is this too vague/confusing?

[danepowell]

Per feedback from @webflo and @joachim-n below, do we just need to spell this out?

The two most commonly recommended Drupal project templates are this project (drupal-composer/drupal-project) and drupal/recommended-project. Comparing the two:

drupal-composer/drupal-project

• Predates drupal/recommended-project
• Documented via this README and Github wiki
• Supported via Github issues and pull requests
• Includes additional features and dependencies such as Drush, Drupal Console, and an enforced minimum PHP version

drupal/recommended-project

• Officially recommended by the Drupal maintainers
• Documented via this change record
• Supported via drupal.org

Both templates follow modern Composer and Drupal best practices (such as using Composer Scaffold) and provide a great out-of-the-box experience. See this discussion for additional information.

I understand that we don't want to editorialize, and I definitely don't want to step on any toes, but I'm not sure this dry comparison captures the fact that drupal-project seems way more user-friendly. The Drupal recommended project is positively spartan:

Maybe that's because discussion happens on drupal.org, but then shouldn't the repo at least mention to go there for support?

Anyway, I'm happy as long as each project at least acknowledges the other's existence so users aren't confused.

[ryanaslett]

This should probably result in a readme in the recommended-project template directory so that it shows up on the subtree splits.

[webflo]

Thanks for working on it. Really appreciated!

[webflo]

The link for drupal-recommended-project is wrong. acquia => drupal

[danepowell]

D'oh, yeah, I was working on acquia/drupal-recommended-project at the same time, we'd like to base it on one of these two upstream templates. I'll fix the link once we come to consensus on the wording.

[joachim-n]

generally has more documentation, more functionality (such as Drush out of the box), and more community support.

This is a bit handwavy... as a user needing to decide which one to use, I'd want to know to more of the practical differences. What will using this project let me do that the other one won't? In what ways will this project restrict me that the other one won't?

[ryanaslett]

I think the primary differentiator is that drupal-project is able to be opinionated, and can ship with multiple features out of the box, whereas the drupal/recommended-project has to stick with strictly what exists, and is tested, in drupal core.

Both projects are starting points, so theres no real limitations to either template, IMO. You get a head start on very common tools with this project. Whereas you start with a blank slate with drupal/recommended-project.

That being said, there are sometimes trade-offs that come with the inclusion of some of these tools, for example, at one time drupal-project came with drupal/console, and when drupal 9 came out, many sites struggled to update because console was not ready for drupal 9 for many months. Oftentimes those site owners would realize that they didnt need drupal/console in the first place, it was just one of the things that came with drupal-project, and that by removing that from their site enabled their adoption of drupal 9. Im not really sure how to distill that kind of complexity into something easy for a lay person to digest however.

[AlexSkrypnyk]

While I agree that a comparison is needed, almost every sentence in this PR needs to be updated as of 2024 to reflect the current state of community adoption of this project. We also need to make sure that there are no biased references like "most commonly" or "likely to eventually".

I'm going to close this PR for now. The requirement is still tracked in #538 and will be addressed in a new PR.