Issue #3192842 by gabesullice, xjm, phenaproxima, lhockley, thalles: Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem

README.md

@@ -0,0 +1,75 @@
+<img alt="Drupal Logo" src="https://www.drupal.org/files/Wordmark_blue_RGB.png" height="60px">
+
+Drupal is an open source content management platform supporting a variety of
+websites ranging from personal weblogs to large community-driven websites. For
+more information, visit the Drupal website, [Drupal.org][Drupal.org], and join
+the [Drupal community][Drupal community].
+
+## Contributing
+
+Drupal is developed on [Drupal.org][Drupal.org], the home of the international
+Drupal community since 2001!
+
+[Drupal.org][Drupal.org] hosts Drupal's [GitLab repository][GitLab repository],
+its [issue queue][issue queue], and its [documentation][documentation]. Before
+you start working on code, be sure to search the [issue queue][issue queue] and
+create an issue if your aren't able to find an existing issue.
+
+Every issue on Drupal.org automatically creates a new community-accessible fork
+that you can contribute to. Learn more about the code contribution process on
+the [Issue forks & merge requests page][issue forks].
+
+## Usage
+
+For a brief introduction, see [USAGE.txt](/core/USAGE.txt). You can also find
+guides, API references, and more by visiting Drupal's [documentation
+page][documentation].
+
+You can quickly extend Drupal's core feature set by installing any of its
+[thousands of free and open source modules][modules]. With Drupal and its
+module ecosystem, you can often build most or all of what your project needs
+before writing a single line of code.
+
+## Changelog
+
+Drupal keeps detailed [change records][changelog]. You can search Drupal's
+changes for a record of every notable breaking change and new feature since
+2011.
+
+## 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].
+
+## Need a helping hand?
+
+Visit the [Support page][support] or browse [over a thousand Drupal
+providers][service providers] offering design, strategy, development, and
+hosting services.
+
+## Legal matters
+
+Know your rights when using Drupal by reading Drupal core's
+[license](/core/LICENSE.txt).
+
+Learn about the [Drupal trademark and logo policy here][trademark].
+
+[Drupal.org]: https://www.drupal.org
+[Drupal community]: https://www.drupal.org/community
+[GitLab repository]: https://git.drupalcode.org/project/drupal
+[issue queue]: https://www.drupal.org/project/issues/drupal
+[issue forks]: https://www.drupal.org/drupalorg/docs/gitlab-integration/issue-forks-merge-requests
+[documentation]: https://www.drupal.org/documentation
+[changelog]: https://www.drupal.org/list-changes/drupal
+[modules]: https://www.drupal.org/project/project_module
+[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
+[service providers]: https://www.drupal.org/drupal-services
+[support]: https://www.drupal.org/support
+[trademark]: https://www.drupal.com/trademark

composer.lock

@@ -528,7 +528,7 @@
             "dist": {
                 "type": "path",
                 "url": "core",
-                "reference": "30eda55b110e77f197ac7b4564502f37b2391f15"
+                "reference": "02fb64caa7f852779c5ba9b94d7b48755612d45d"
             },
             "require": {
                 "asm89/stack-cors": "^1.1",
@@ -705,7 +705,7 @@
                         "[web-root]/example.gitignore": "assets/scaffold/files/example.gitignore",
                         "[web-root]/index.php": "assets/scaffold/files/index.php",
                         "[web-root]/INSTALL.txt": "assets/scaffold/files/drupal.INSTALL.txt",
-                        "[web-root]/README.txt": "assets/scaffold/files/drupal.README.txt",
+                        "[web-root]/README.md": "assets/scaffold/files/drupal.README.md",
                         "[web-root]/robots.txt": "assets/scaffold/files/robots.txt",
                         "[web-root]/update.php": "assets/scaffold/files/update.php",
                         "[web-root]/web.config": "assets/scaffold/files/web.config",

core/USAGE.txt

@@ -1,30 +1,3 @@
-
-CONTENTS OF THIS FILE
----------------------
-
- * About Drupal
- * Configuration and features
- * Installation profiles
- * Appearance
- * Developing for Drupal
- * More information
-
-
-ABOUT DRUPAL
-------------
-
-Drupal is an open source content management platform supporting a variety of
-websites ranging from personal weblogs to large community-driven websites. For
-more information, see the Drupal website at https://www.drupal.org, and join
-the Drupal community at https://www.drupal.org/community.
-
-Legal information about Drupal:
- * Know your rights when using Drupal:
-   See LICENSE.txt in the "core" directory.
- * Learn about the Drupal trademark and logo policy:
-   https://www.drupal.com/trademark
-
-
 CONFIGURATION AND FEATURES
 --------------------------
 
@@ -76,7 +49,6 @@ More about installation profiles and distributions:
  * Develop your own installation profile or distribution:
    https://www.drupal.org/docs/distributions/creating-distributions
 
-
 APPEARANCE
 ----------
 
@@ -122,22 +94,3 @@ More about developing:
    https://api.drupal.org/api/drupal/9
  * Learn from documented Drupal API examples:
    https://www.drupal.org/project/examples
-
-
-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.

core/assets/scaffold/files/drupal.README.md

@@ -0,0 +1,75 @@
+<img alt="Drupal Logo" src="https://www.drupal.org/files/Wordmark_blue_RGB.png" height="60px">
+
+Drupal is an open source content management platform supporting a variety of
+websites ranging from personal weblogs to large community-driven websites. For
+more information, visit the Drupal website, [Drupal.org][Drupal.org], and join
+the [Drupal community][Drupal community].
+
+## Contributing
+
+Drupal is developed on [Drupal.org][Drupal.org], the home of the international
+Drupal community since 2001!
+
+[Drupal.org][Drupal.org] hosts Drupal's [GitLab repository][GitLab repository],
+its [issue queue][issue queue], and its [documentation][documentation]. Before
+you start working on code, be sure to search the [issue queue][issue queue] and
+create an issue if your aren't able to find an existing issue.
+
+Every issue on Drupal.org automatically creates a new community-accessible fork
+that you can contribute to. Learn more about the code contribution process on
+the [Issue forks & merge requests page][issue forks].
+
+## Usage
+
+For a brief introduction, see [USAGE.txt](/core/USAGE.txt). You can also find
+guides, API references, and more by visiting Drupal's [documentation
+page][documentation].
+
+You can quickly extend Drupal's core feature set by installing any of its
+[thousands of free and open source modules][modules]. With Drupal and its
+module ecosystem, you can often build most or all of what your project needs
+before writing a single line of code.
+
+## Changelog
+
+Drupal keeps detailed [change records][changelog]. You can search Drupal's
+changes for a record of every notable breaking change and new feature since
+2011.
+
+## 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].
+
+## Need a helping hand?
+
+Visit the [Support page][support] or browse [over a thousand Drupal
+providers][service providers] offering design, strategy, development, and
+hosting services.
+
+## Legal matters
+
+Know your rights when using Drupal by reading Drupal core's
+[license](/core/LICENSE.txt).
+
+Learn about the [Drupal trademark and logo policy here][trademark].
+
+[Drupal.org]: https://www.drupal.org
+[Drupal community]: https://www.drupal.org/community
+[GitLab repository]: https://git.drupalcode.org/project/drupal
+[issue queue]: https://www.drupal.org/project/issues/drupal
+[issue forks]: https://www.drupal.org/drupalorg/docs/gitlab-integration/issue-forks-merge-requests
+[documentation]: https://www.drupal.org/documentation
+[changelog]: https://www.drupal.org/list-changes/drupal
+[modules]: https://www.drupal.org/project/project_module
+[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
+[service providers]: https://www.drupal.org/drupal-services
+[support]: https://www.drupal.org/support
+[trademark]: https://www.drupal.com/trademark

core/assets/scaffold/files/drupal.README.txt

@@ -1,143 +0,0 @@
-
-CONTENTS OF THIS FILE
----------------------
-
- * About Drupal
- * Configuration and features
- * Installation profiles
- * Appearance
- * Developing for Drupal
- * More information
-
-
-ABOUT DRUPAL
-------------
-
-Drupal is an open source content management platform supporting a variety of
-websites ranging from personal weblogs to large community-driven websites. For
-more information, see the Drupal website at https://www.drupal.org, and join
-the Drupal community at https://www.drupal.org/community.
-
-Legal information about Drupal:
- * Know your rights when using Drupal:
-   See LICENSE.txt in the "core" directory.
- * Learn about the Drupal trademark and logo policy:
-   https://www.drupal.com/trademark
-
-
-CONFIGURATION AND FEATURES
---------------------------
-
-Drupal core (what you get when you download and extract a drupal-x.y.tar.gz or
-drupal-x.y.zip file from https://www.drupal.org/project/drupal) has what you
-need to get started with your website. It includes several modules (extensions
-that add functionality) for common website features, such as managing content,
-user accounts, image uploading, and search. Core comes with many options that
-allow site-specific configuration. In addition to the core modules, there are
-thousands of contributed modules (for functionality not included with Drupal
-core) available for download.
-
-More about configuration:
- * Install, update, and maintain Drupal:
-   See INSTALL.txt and UPDATE.txt in the "core" directory.
- * Learn about how to use Drupal to create your site:
-   https://www.drupal.org/documentation
- * Follow best practices:
-   https://www.drupal.org/best-practices
- * Download contributed modules to /modules to extend Drupal's functionality:
-   https://www.drupal.org/project/project_module
- * See also: "Developing for Drupal" for writing your own modules, below.
-
-
-INSTALLATION PROFILES
----------------------
-
-Installation profiles define additional steps (such as enabling modules,
-defining content types, etc.) that run after the base installation provided
-by core when Drupal is first installed. There are two basic installation
-profiles provided with Drupal core.
-
-Installation profiles from the Drupal community modify the installation process
-to provide a website for a specific use case, such as a CMS for media
-publishers, a web-based project tracking tool, or a full-fledged CRM for
-non-profit organizations raising money and accepting donations. They can be
-distributed as bare installation profiles or as "distributions". Distributions
-include Drupal core, the installation profile, and all other required
-extensions, such as contributed and custom modules, themes, and third-party
-libraries. Bare installation profiles require you to download Drupal Core and
-the required extensions separately; place the downloaded profile in the
-/profiles directory before you start the installation process.
-
-More about installation profiles and distributions:
- * Read about the difference between installation profiles and distributions:
-   https://www.drupal.org/docs/distributions/creating-distributions
- * Download contributed installation profiles and distributions:
-   https://www.drupal.org/project/project_distribution
- * Develop your own installation profile or distribution:
-   https://www.drupal.org/docs/distributions/creating-distributions
-
-
-APPEARANCE
-----------
-
-In Drupal, the appearance of your site is set by the theme (themes are
-extensions that set fonts, colors, and layout). Drupal core comes with several
-themes. More themes are available for download, and you can also create your own
-custom theme.
-
-More about themes:
- * Download contributed themes to /themes to modify Drupal's appearance:
-   https://www.drupal.org/project/project_theme
- * Develop your own theme:
-   https://www.drupal.org/docs/theming-drupal
-
-
-DEVELOPING FOR DRUPAL
----------------------
-
-Drupal contains an extensive API that allows you to add to and modify the
-functionality of your site. The API consists of "hooks", which allow modules to
-react to system events and customize Drupal's behavior, and functions that
-standardize common operations such as database queries and form generation. The
-flexible hook architecture means that you should never need to directly modify
-the files that come with Drupal core to achieve the functionality you want;
-instead, functionality modifications take the form of modules.
-
-When you need new functionality for your Drupal site, search for existing
-contributed modules. If you find a module that matches except for a bug or an
-additional needed feature, change the module and contribute your improvements
-back to the project in the form of a "patch". Create new custom modules only
-when nothing existing comes close to what you need.
-
-More about developing:
- * Search for existing contributed modules:
-   https://www.drupal.org/project/project_module
- * Contribute a patch:
-   https://www.drupal.org/patch/submit
- * Develop your own module:
-   https://www.drupal.org/developing/modules
- * Follow programming best practices:
-   https://www.drupal.org/docs/develop/standards
- * Refer to the API documentation:
-   https://api.drupal.org/api/drupal/9
- * Learn from documented Drupal API examples:
-   https://www.drupal.org/project/examples
-
-
-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.

core/composer.json

@@ -217,7 +217,7 @@
                 "[web-root]/example.gitignore": "assets/scaffold/files/example.gitignore",
                 "[web-root]/index.php": "assets/scaffold/files/index.php",
                 "[web-root]/INSTALL.txt": "assets/scaffold/files/drupal.INSTALL.txt",
-                "[web-root]/README.txt": "assets/scaffold/files/drupal.README.txt",
+                "[web-root]/README.md": "assets/scaffold/files/drupal.README.md",
                 "[web-root]/robots.txt": "assets/scaffold/files/robots.txt",
                 "[web-root]/update.php": "assets/scaffold/files/update.php",
                 "[web-root]/web.config": "assets/scaffold/files/web.config",

core/tests/Drupal/BuildTests/Framework/Tests/BuildTestTest.php

@@ -42,7 +42,7 @@ class BuildTestTest extends BuildTestBase {
       'autoload.php',
       'composer.json',
       'index.php',
-      'README.txt',
+      'README.md',
       '.git',
       '.ht.router.php',
     ];

core/tests/Drupal/Tests/ComposerIntegrationTest.php

@@ -19,6 +19,11 @@ class ComposerIntegrationTest extends UnitTestCase {
 
   /**
    * Tests composer.lock content-hash.
+   *
+   * If you have made a change to composer.json, you may need to reconstruct
+   * composer.lock. Follow the link below for further instructions.
+   *
+   * @see https://www.drupal.org/about/core/policies/core-dependencies-policies/managing-composer-updates-for-drupal-core
    */
   public function testComposerLockHash() {
     $content_hash = self::getContentHash(file_get_contents($this->root . '/composer.json'));
@@ -142,7 +147,7 @@ class ComposerIntegrationTest extends UnitTestCase {
       ['example.gitignore', 'assets/scaffold/files/example.gitignore'],
       ['index.php', 'assets/scaffold/files/index.php'],
       ['INSTALL.txt', 'assets/scaffold/files/drupal.INSTALL.txt'],
-      ['README.txt', 'assets/scaffold/files/drupal.README.txt'],
+      ['README.md', 'assets/scaffold/files/drupal.README.md'],
       ['robots.txt', 'assets/scaffold/files/robots.txt'],
       ['update.php', 'assets/scaffold/files/update.php'],
       ['web.config', 'assets/scaffold/files/web.config'],