Add README.md to composer project templates

What about adding both link? Acknowledging one is more for developers

@smustgrave, that was also the conclusion I came to yesterday, so +1 for that suggestion.

But thinking some more about this, we should do our utmost to make sure that the drupal/recommended-project project ranks best, when people search for words such as "install Drupal" or "composer drupal" in search engines, including packagist.org, Github, Gitlab, etc.

The reason is simple: This package should be the starting point for most new Drupal projects.

@tedbow: Every time I want to remember how to start Drupal project via composer I search for something like "drupal recommended project" the first google result for me is https://github.com/drupal/recommended-project. This page has no explanation

Yes, me too. But we only do this because we know "recommended" is the magic word to unlock Drupal :)

We can solve these two tasks (rank it better, describe it better) by adding a detailed README.md:

1. Make drupal/recommended-project rank well in searches on how to install or download Drupal
2. Make it immediately clear to a new user that this is the right method to start a new project with, if they find it on packagist.org, Github, Gitlab, etc.

So we need to look at this both from a SEO perspective, but also giving more info, directly in the README.md file, wherever it is found.

@tedbow: My experience with core development is an issue with that much text that this will take a long time, months or years, to be reviewed and committed.

Could this be solved by re-using the great and welcoming text from https://github.com/drupal/drupal/blob/10.1.x/README.md?

At the very top we add a new section with a short text outlining that this is the recommended starting point for new Drupal project, as well as the two links at the top, followed by a copy-paste of https://github.com/drupal/drupal/blob/10.1.x/README.md.

We should keep LegacyProject/README.md at the bare minimum, since we only want RecommendedProject/README.md to perform well in the search engines.

PS. This was the proposal in both files, before the update:

• /composer/Template/LegacyProject/README.md
• /composer/Template/RecommendedProject/README.md

For instructions on using this project see [Starting a Site Using Drupal Composer Project Templates](https://www.drupal.org/docs/develop/using-composer/starting-a-site-using-drupal-composer-project-templates)

"RecommendedProject README.md" mostly looks great, thanks! I opened a few threads in the MR for some minor tweaks/improvements.

The other concern is that we're actively trying to move to GitLab for issues, and kill the d.o issue queues. Presumably we're going to have redirects from paths like https://www.drupal.org/project/issues/drupal → to whatever the right place is on GitLab, so maybe it doesn't matter. But this seems like exactly the sort of thing that will be easy to forget as part of that migration, and it'll be 4+ years before we realize these README.md files are linking to the legacy location.

Otherwise, I think this is a major improvement, and hope we get this done soon.

Thanks again!
-Derek

Great, thanks for a fast review Derek! It would be nice if we could get this launched before too long.

I have updated the files according to your comments, and used a link to https://github.com/drupal/recommended-project in LegacyProject -- there are several options, but it seemed like the best choice.

I cannot see how I can resolve your comments ... I tried adding a comment ("Done!") to one of them, but it made no difference ...

And yes, someone should make a perpetual "Remind me in 365 days to check and update links", to make sure links are updated after the move to Gitlab :)

PS. I am not changing status, but it's still in "Needs Review", so anyone should feel free to weigh in with more reviews.

Great, thanks!

Only the author of the MR (@tedbow) or core committers can currently resolve MR threads. Hopefully this will be fixed before the full GitLab migration. 😅

Just re-reviewed the MR. Sorry, I missed one very minor thing. After that, I'd RTBC this...

Thanks again!
-Derek

Thanks for confirming, I was also suspecting something like permissions was the cause, and dreamed forward to a future, when both issues and MRs will be on Gitlab :-)

No problem with the update, it's done.

Looks great to me. No further objections. RTBC!

p.s. I see the MR is targeting the 9.3.x branch, but I don't think it matters at all since this is for 2 brand new files, so this should apply cleanly to any branch. AFAICT, core committers always use a patch locally to commit changes, so the actual MR merging / mechanics don't exactly matter.

Fantastic! I thank you for swift and constructive suggestions, it was a pleasure working with you.

Phew, about the branch. I have previously wrangled and failed with re-basing a core patch, so that's great news.

Yeah, the other thing only the MR author or core committers can do (for now), is change an MR's target branch. It's another PITA / bottleneck for the MR-only workflow. But as I said, in this particular case, it doesn't matter. 😅

But yay, it was a pleasure working with you, too! Thanks for the quick turn-around on the fixes and for helping to get this done.

The legacy project readme looks good.

The text for recommended project has a lot of duplication with core/README.md and I don't see us keeping them in sync. Could we refer to it instead?

There is duplication, because I copied it from core/README.md, like I suggested in #25 :)

We need to consider which of the two repos we want to guide new users toward via the search engines, but also which README.md new users will meet first in their installation, and have at hand.

1. SEO and getting started

Do we want new users to find https://git.drupalcode.org/project/drupal first, and leave them wondering how to get started with installing Drupal?

2. Info at the finger tip

Since the drupal/recommended-project README.md will be in the root of every newly created project, it is the README.md new users will see first, whereas the original is more hidden, in the /core folder. Referring to core/README.md is possible, but it seems clunky to me. I would prefer to put the relevant info directly in the README.md file, in the root of the Drupal installation, directly available when the info is needed.

I see four scenarios, where I prefer #1 most (swapping), and #4 least (keep it in /core and refer):

1. We could swap them, and make the README.md in drupal/recommended-project the primary, and refer to it from a smaller /core/README.md
2. We could detach the drupal/recommended-project README.md and perhaps slim it down
3. We could maintain both, and keep them in sync
4. We could refer to core/README.md from drupal/recommended-project/README.md

It would be great to not let this issue stall again, and keep it moving. Every day without a README.md in the composer project templates only means more wasted time and frustrations for new Drupal users.

Maybe potentially new Drupal users don't even find this specific project, which is after all the starting point for new Drupal projects, and instead give up and use another CMS.

I don't see a lot of changes happen for the README personally so wonder if when changes are made they are also updated in in the composer?

I don't think we should do #3 so moving back to needs work to consider #1 vs #2 vs #4 from #36. The issue isn't how often it's updated, it's it getting out of sync when that happens.

Thanks for the feedback @catch.

Dries proposed in Drupal is for ambitious site builders to evolve the Drupal vision statement to this:

Drupal is for ambitious site builders

If the Drupal community really values the Drupal site builder and we want to maintain the user base and prevent it from shrinking any further, this issue needs to keep moving. We need to make it easier to find the necessary information, but also clarify what the individual repository is about.

Let's do it like this:

For the next 14 days (May 23 - June 6, 2023) there will be debate and voting, and the model getting the most votes will get implemented after 7th of June 2023, after the voting and debate ends. I have updated the Issue Summary with this info.

Here's my vote: #1 "Swap: We could swap them, and make the README.md in drupal/recommended-project the primary, and refer to it from a smaller /core/README.md"

It's so great to see all the activity in the Project Browser initiative, it'll be a huge improvement.

But, we need to get the new users to use Drupal first, before they can use the Project Browser. They need to be guided to the right Composer template to download, and easily get help when stuck, directly in that folder.

I know, updating a README isn't as exciting as working on Project Browser. But it is also quite important, for many different reasons already outlined.

Ambitious Site Builders like thorough documentation, and would love to find an awesome README in the root of their new Drupal projects.