diff --git a/README.md b/README.md
new file mode 100644
index 00000000000..c3e53713409
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+
+
+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
diff --git a/composer.lock b/composer.lock
index e1565780262..5b3b0dcff04 100644
--- a/composer.lock
+++ b/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",
diff --git a/README.txt b/core/USAGE.txt
similarity index 75%
rename from README.txt
rename to core/USAGE.txt
index d0964b0a942..e9efa61aa1f 100644
--- a/README.txt
+++ b/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.
diff --git a/core/assets/scaffold/files/drupal.README.md b/core/assets/scaffold/files/drupal.README.md
new file mode 100644
index 00000000000..c3e53713409
--- /dev/null
+++ b/core/assets/scaffold/files/drupal.README.md
@@ -0,0 +1,75 @@
+
+
+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
diff --git a/core/assets/scaffold/files/drupal.README.txt b/core/assets/scaffold/files/drupal.README.txt
deleted file mode 100644
index d0964b0a942..00000000000
--- a/core/assets/scaffold/files/drupal.README.txt
+++ /dev/null
@@ -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.
diff --git a/core/composer.json b/core/composer.json
index 5bbabf5b1ba..79019a8cf65 100644
--- a/core/composer.json
+++ b/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",
diff --git a/core/tests/Drupal/BuildTests/Framework/Tests/BuildTestTest.php b/core/tests/Drupal/BuildTests/Framework/Tests/BuildTestTest.php
index b505ef83522..2add2c5aa84 100644
--- a/core/tests/Drupal/BuildTests/Framework/Tests/BuildTestTest.php
+++ b/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',
];
diff --git a/core/tests/Drupal/Tests/ComposerIntegrationTest.php b/core/tests/Drupal/Tests/ComposerIntegrationTest.php
index d74cf420278..33a7bd11395 100644
--- a/core/tests/Drupal/Tests/ComposerIntegrationTest.php
+++ b/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'],