Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem

I'd like to majorly +1 this idea. This is something I would 100% expect to see from any software hosted on GitHub, GitLab, or any comparable platform. It's long overdue for Drupal.

Massive +1 to this idea. Really good plan, and the in-progress work looks great.

It's a +1 from me.

I think a well written README that aligns with modern standards also goes a long way in establishing credibility. In turn, it can be a deciding factor for a developer who may be on the fence about "diving in" to the wonderful world of Drupal.

Lovely!

We have the option to create a new README.md alongside the existing README.txt, and the MD file will be picked up first to display on github: https://github.com/theodoreb/test-readme/tree/main

Not saying we should do that, just that it is possible.

This is looking really good! From my point of view, RTBC.

RTBC +1 with followup to update the content and fine tune what is the audience for this file, and where we should send them.

probably would need to credit folks from related issue too.

So IIRC the last time we tried to replace SOMETHING.txt with a SOMETHING.md, we got blocked on an issue to define which markdown specification we would use. I am perfectly fine bypassing that discussion as it was very frustrating to me and seemed mostly irrelevant, but we should be aware of that past precedent. We should also be sure we look for past issues of people who might have tried to make this conversion, close them as dupes, and credit them here.

xjm helped with the rebase. ;)

Looks like @nod_ already found one of the past issues. It was postponed on #2506415: Adopt Markdown for README.txt and other documentation, which has feedback from @jhodgdon that we should make sure we address here.

Adding some more related issues (including the coding standards issue that every attempt to add markdown anywhere has been blocked on). Ironically, I can't even find my own issue related to the changelog and release notes that got blocked on it.

Looks like a lot of the past discussion was actually related to #1674976: Allow README.md to optionally render as the project page, which is a much bigger scope that shouldn't be conflated, but that's what the precedent of blocking this on linting and the exact markdown spec we support and contrib readmes and etc. has been all tangled up with.

Crossposting Jennifer's comments:

I am not convinced of this from the issue summary "Using Markdown ... will make README, UPDATE, et al, a lot nicer to read."

Markdown is only nicer to read, in my opinion, if you are reading it after it has been processed into HTML or some other formatted output. I don't think it's nicer to read if you're reading it in plain text.

So if we want to switch to Markdown, we would I think also need a plan to have an easy way for our README files to be displayed in formatted output. This happens automatically at Github for instance, but I do not know whether the software of drupalcode.org supports it.

And we'd need to consider that:
- There are a LOT of contrib projects out there. Would you want to make it a standard that they all would need to switch to .md too (or would be encouraged to)?
- Most people don't read the README files by visiting drupalcode.org or something like that. Most of us would be looking at them I think in plain text. At least... well that is what I do. For instance I download the Foo module and read its README file either in a plain text editor or using the more utility at the command line. How do you propose people would get formatted output in that situation?

I guess the other question is whether most of our README files really need Markdown. I guess if they don't, it the formatting wouldn't really get in the way of those of us who would tend to read them in plain text.

Anyway... I think your case would be more convincing if:

a) You gave an example of what a Markdown formatted README from our project would actually look at, so we could see both how annoying it would be to see it in plain text and how beneficial it would be to see it formatted.

b) You tested to see if drupalcode.org can do Markdown formatting, and found out which flavor of Markdown it supports if so (might not be "commonmark").

From my perspective, acceptable answers are "That was 2015; this is 2021; basically everyone uses README.md nowadays" and "We don't need to lint our README" and "We aren't using any syntax advanced enough such that the spec really matters". Maybe that would let us get past the constant postponing of markdown-related issues on the coding standards issue.

Crediting @thalles from #3056153: Rename README.txt to README.md for a prior attempt.

As a Product Manager, I do think this is the way to go for all "text-y" documentation files, but most definitely for README.

These days, .md is the defacto standard, since it's been used on GitHub since time immemorial, and since GitHub adoption took off like a rocketship in the mid-2010s.

A crude metric to demonstrate this:

Google search for "readme.txt": "About 25,800,000 results"
Google search for "readme.md": "About 55,400,000 results"

Additionally, we're now on a code repository browser that natively supports .md files; see https://git.drupalcode.org/project/webform as an example. It makes sense to leverage this, especially since from a usability POV, the difference from within the code browser is pretty night and day:

The concerns raised in the other issue were around fears for the legibility for plaintext readers, but Markdown is explicitly designed to be legible in a plaintext editor:

README.txt

MORE INFORMATION
----------------

 * See the Drupal.org online documentation:
   https://www.drupal.org/documentation

 * For a list of security announcements, see the "Security advisories" page at
   https://www.drupal.org/security (available as an RSS feed). This page also
   describes how to subscribe to these announcements via email.

 * For information about the Drupal security process, or to find out how to
   report a potential security issue to the Drupal security team, see the
   "Security team" page at https://www.drupal.org/drupal-security-team

 * For information about the wide range of available support options, visit
   https://www.drupal.org and click on Community and Support in the top or
   bottom navigation.

README.md

## Security

For a list of security announcements, see the [Security advisories
page][Security advisories] (available as [an RSS feed][security RSS]). This
page also describes how to subscribe to these announcements via email.

For information about the Drupal security process, or to find out how to report
a potential security issue to the Drupal security team, see the [Security team
page][security team].

...

[security advisories]: https://www.drupal.org/security
[security RSS]: https://www.drupal.org/security/rss.xml
[security team]: https://www.drupal.org/drupal-security-team

I'm also prone to popping things open in a plaintext editor (vi FTW! :P), and don't find the difference here stark enough to cause me concern. The "layer of indirection" way we're linking in this MR obfuscates this somewhat, but is also a pretty nice convention, especially for links that repeat. (Cool... I didn't know you could do that!)

So, big +1 to the general goal, and for moving forward with this. I need to review the actual content, which I will do shortly.

We need a change record and a release note because we're changing a scaffolded file. It's not uncommon for a projects root composer.json to have something like:

        "drupal-scaffold": {
            "locations": {
                "web-root": "web/"
            },
            "file-mapping": {
                "[web-root]/README.txt": false
            }
        }

In order to not scaffold the README.txt on a site. This change will result in site's getting a README.md when they are explicitly trying to not have this available.

Looks like there is already a release note in the issue summary, so removing that tag (and adding information about the scaffold file). I took a stab at a change record: https://www.drupal.org/node/3196810

Restoring RTBC in the hopes that these will do the trick.

Ok! Sorry for the delay; finally had a chance to review the text in more detail.

So the old README had both factual errors (e.g. "For information about the wide range of available support options, visit https://www.drupal.org and click on Community and Support in the top or bottom navigation." which... is not a thing. :P) and a confusing flow ("This is what Drupal is... now KNOW YOUR RIGHTS!!")

The new version flows well, and has ample links directly to helpful resources vs. tossing people in a general area. I love pushing the community front and centre, since that's a big reason to use Drupal, and also love informing people about modules front and centre, since that's where 90% of the power of Drupal is, and making that explicit removes a lot of face-desking.

Looking forward to further improvements, e.g. to the new USAGE.txt :D Thanks SO much Gabe and everyone else who contributed to this! <3

Committed and pushed to 9.2.x. Thanks!

Oh. I got freaked out by the composer.lock change, but was informed that if this isn't done a test fails because README is part of the scaffold. The More You Know™

Pretty :) https://github.com/drupal/drupal

We need to mention this in the release note because plenty of people remove the readme from their site builds eg. https://www.acquia.com/README.txt and I'm pretty sure people don't a README.md all about Drupal on their top-level either.