UPGRADE.txt only mentions migrating from Drupal 6 and 7, UPDATE.txt only mentions 8-8 updates

Hii @webchick I added updated the update.txt to point to said handbook page.
Please review.

--- a/core/UPDATE.txt
+++ b/core/UPDATE.txt

+++ b/core/UPDATE.txt
@@ -9,8 +9,8 @@ into a new Drupal 8 site. The tools and process are currently experimental,

@@ -9,8 +9,8 @@ into a new Drupal 8 site. The tools and process are currently experimental,
 rather than being fully supported, so be sure to test in a development
 environment. You will need to use the core Migrate Drupal UI module which
 provides a user interface for the Migrate and Migrate Drupal modules included
-in core. See https://www.drupal.org/upgrade/migrate for details, and
-https://www.drupal.org/node/2167633 for known issues.
+in core. See https://www.drupal.org/docs/8/upgrade/upgrading-between-drupal-8-major-versions-eg-from-drupal-8-to-drupal-9 for
+details, and https://www.drupal.org/node/2167633 for known issues.
 

We need to update some of the other text around this as well, unfortunately changing the link isn't enough.

I would add a new section (above the section about Drupal 6 and 7) for instructions on updating from Drupal 8 to 9.

Then keep the existing version about updating from Drupal 6 and 7 (but changing language so it says updating to Drupal 9).

I attempted to add what catch mentioned in his comment. References to Drupal 8 updated to Drupal 9. There's a quick section about upgrading from D8 to D9 as well as the links mentioned above.

+++ b/core/UPDATE.txt
@@ -1,11 +1,29 @@
+This document describes how to update your Drupal site between 9.x.x minor and
+patch versions; for example, from 9.1.2 to 9.1.3, or from 9.3.5 to 9.4.0.
+
+Upgrade Drupal 8 to Drupal 9:

Right after it says this is about minor versions it goes into a major version update. Quite contraditory :)

We need to redefine the scope of this file entirely to cover both.

Also, you have somewhat header looking items, those would be important to make actual headers.

Parenting into the Drupal 9 release process :)

Excellent points. I've updated the patch to show that the file covers both upgrading to D9 as well as updating D9 to minor and patch version. I've also updated the headers to match the other headers in the document.

Since we're planning on changing the *minimum* requirements for databases, that ought to be called out as well.

Is this the best place to get the minimum requirements info? https://www.drupal.org/docs/9/how-drupal-9-is-made-and-what-is-included/...

Requirements should be here: https://www.drupal.org/docs/8/system-requirements

But we need a Drupal 9 version of that page.

A link to the new documentation would probably be good, but for now I think we'd be alright to add the known requirements, right?

+++ b/core/UPDATE.txt
@@ -1,11 +1,40 @@
+Drupal 9 will require at least PHP 7.3. Drupal 9 (and 8) do not yet support PHP
+7.4, but work is ongoing. Version requirements will be raised for MySQL (at

I think Drupal 9 and 8 support 7.4 now as #3086374: Make Drupal 8 & 9 compatible with PHP 7.4 was fixed

1. +++ b/core/UPDATE.txt
   @@ -1,11 +1,40 @@
   +SYSTEM REQUIREMENTS FOR DRUPAL 9
   +----------------
   +Drupal 9 will require at least PHP 7.3. Drupal 9 (and 8) do not yet support PHP
   +7.4, but work is ongoing. Version requirements will be raised for MySQL (at
   

   I don't think we should duplicate the requirements info here - for example this statement is already out of date.

2. +++ b/core/UPDATE.txt
   @@ -1,11 +1,40 @@
   +
   +UPGRADE DRUPAL 8 TO DRUPAL 9
   +----------------
   +To upgrade from Drupal 8 to Drupal 9, ensure your site is up to the latest
   +version. Upgrades are only supported from the final LTS release and one
   +previous (e.g. Drupal 8.8+), not from e.g. Drupal 8.3. Your system must also
   

   Should specify ensure your Drupal 8 site is running the latest version or similar - otherwise it's not clear that we're telling people to do an interim update.

3. +++ b/core/UPDATE.txt
   @@ -1,11 +1,40 @@
   +version. Upgrades are only supported from the final LTS release and one
   +previous (e.g. Drupal 8.8+), not from e.g. Drupal 8.3. Your system must also
   +meet the minimum system requirements for the next version, e.g. PHP 7.2+.
   +
   

   Also need to drop the PHP 7.2 reference from here as well.

From my understanding, #25 did not address concerns in #23 correct me if I were worng.

1. +++ b/core/UPDATE.txt
   @@ -6,18 +6,18 @@
   +Drupal 9 will require at least PHP 7.3. Version requirements will be
   +raised for MySQL (atleast to 5.7),MariaDB (at least to 10.2), PostgreSQL
   +and SQLite as well. While Drupal core does not require Drush, many people
   

   Will require, will be raised do not make sense to me. For me they should be certain versions, for example MySQL 5.7+, MariaDB 10.2 +, PostgreSQL x.y.z+, SQLite: x.y.z+

   (x.y.z is a placeholder)

2. +++ b/core/UPDATE.txt
   @@ -6,18 +6,18 @@
   +do use Drush. As of this writing Drush will only provide Drupal 9 compatibility
   +in Drush 10.
   

   Drush is not a part of Core, no sure we should mention it here. If we have to mention it, I think it's good to tell people that they have to install it as a part of the codebase first (composer require drush/drush), or it's impossible to run Drush/Drush 10 in Drupal 9.

   10.0.0-rc4 installer throws an error #4234

   @weitzman: Drush must be installed as a dependency of your composer built site. It's unsupported as a global program for quite a while now. A global program to consider is drush launcher, and that hands of to the drush that's in your project.

   https://github.com/drush-ops/drush/issues/4234#issuecomment-546628901

Resetting the title.

This is instructions specific to upgrading a site from Drupal 8 to Drupal 9 (things like ensuring the Drupal 8 site is updated to the latest version including contrib modules). We don't have a mechanism for migrating from 8 to 9 with migrate.

By being put in UPGRADE.txt, the patch currently mixes those instructions with migrating from Drupal 6 and Drupal 7.

I'm wondering a bit if the change here should just to be to explicitly point people to UPDATE.txt and a handbook page, rather than duplicating information elsewhere.

Hello @catch @jungle
I have update the patch.

Please review it.

You uploaded a wrong interdiff :p

Hello @jungle,

I am sorry for it.
Please review updated interdiff.

+++ b/core/UPDATE.txt
@@ -6,18 +6,20 @@
+Drupal core does not require Drush, many people do use Drush. If you use Drush, ¶
...
+To upgrade from Drupal 8 to Drupal 9, ensure your Drupal 8 site is running ¶
+the latest version or similar. Upgrades are only supported from the final LTS ¶

Unexpected tail spaces

Updated the patch and interdiff.
KIndly review it.

Maybe it's good leaving this to someone who is more professional or from the documentation team, I am not a native English speaker and can not help to write better documentation. I could only review trivial things. This is a simple task but an important one, the targeted readers are all Drupal people.

@neelam_wadhwani I appreciate your effects! But I'd suggest stopping submitting new patches for a while.

Another possibility here would be to literally rename this file to MIGRATE.txt, then just ensure that UPDATE.txt includes the possibility of updating from Drupal 8 to 9.

Re-titling.

There are quite a few questions still going, so I don't think this will be the final--but I thought I'd just give the MIGRATE.txt idea a try. I thought we could refer updates (minor versions, 9.1.0 to 9.2.0, etc.) to UPDATE.txt and migrating (might make more sense to use UPGRADE.txt so we don't confuse people about the migrate module?) or upgrading from 6, 7, or 8 to Drupal 9 to the MIGRATE.txt file?

1. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +This document describes how to upgrade your Drupal site from major versions--6,
   +7, or 8--to Drupal 9. For information on updating your Drupal 9 site for minor
   

   Why the double dash? Please remove it.

2. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +final LTS release and one previous (e.g. Drupal 8.8+), not from e.g. Drupal
   +8.3. Your system must also meet the minimum system requirements for the next
   

   Can we change " (e.g. Drupal 8.8+), not from e.g. Drupal 8.3" to "(e.g. Drupal 8.8 or higher). When you are on Drupal 8.7 or a lower version, then please update first to Drupal 8.8 or higher before updating your site to Drupal 9"

3. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +Next, you'll need to ensure you do not have deprecated code in your site that
   +is removed in the next major version, and fix it if required. The Upgrade
   

   Can we change this to "Next, you'll need to ensure that your site does not use code that is dependent on API's that have been removed in Drupal 9. For all removed API's there are recommended replacement API's."

4. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +major-versions-eg-from-drupal-8-to-drupal-9 for details, and https://www.drupal
   +.org/node/2167633 for known issues.
   ...
   +https://www.drupal.org/node/2167633 for known issues.
   

   Can we change the link to: https://www.drupal.org/docs/8/upgrade/known-issues-when-upgrading-from-d...

5. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +into a new Drupal 9 site. The tools and process are currently experimental,
   +rather than being fully supported, so be sure to test in a development
   

   Are we sure that the status of the migration is experimental instead of fully supported?

6. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,76 @@
   +    (https://www.drupal.org/project/drupal).
   

   Not the correct link. It should be: https://www.drupal.org/project/drupal/releases

7. +++ b/core/UPDATE.txt
   @@ -1,61 +1,16 @@
    This document describes how to update your Drupal site between 8.x.x minor and
   

   Please change "8.x.x" to "9.x.x".

8. +++ b/core/UPDATE.txt
   @@ -1,61 +1,16 @@
   +information on upgrading your site from Drupal 6, 7, or 8 to version 9--see the
   

   Why the double dash? Can we change it to "to version 9. See the"

9. +++ b/core/UPDATE.txt
   @@ -1,61 +1,16 @@
   +patch versions; for example, from 9.1.2 to 9.1.3, or from 9.3.5 to 9.4.0. For
   +information on upgrading your site from Drupal 6, 7, or 8 to version 9--see the
   +MIGRATE.txt file.
   ...
   +To upgrade from a previous major version (for example, Drupal 7 or 8), refer to
   +MIGRATE.txt in the core directory.
   

   We have the same text twice.

Here are those changes--so are we good with using MIGRATE.txt?

And you're right, migrate is no longer experimental, so I changed that to a recommendation to test in a dev environment first.

All my points are addressed.
For me it is RTBC.

@owenpm3: Thank you for working on this.

1. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +UPGRADE DRUPAL 8 TO DRUPAL 9
   +----------------
   ...
   +UPGRADE DRUPAL 6 OR 7 TO DRUPAL 9
   +----------------
   

   The dashes don't match up to the previous line length, for all other titles they do match.

2. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +version of Drupal 8 before proceeding. Upgrades are only supported from the
   +final LTS release and one previous (e.g. Drupal 8.8 or higher). When you are
   +on Drupal 8.7 or a lower version, then please update first to Drupal 8.8 or
   

   e.g. = for example
   i.e. = that is

   I think this should say "i.e. Drupal 8.8 or higher".

   Also, "When you are on Drupal 8.7" is better as "If you are on Drupal 8.7"?

3. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +Next, you'll need to ensure that your site does not use code that is dependent
   +on API's that have been removed in Drupal 9. For all removed API's there are
   +recommended replacement API's. The Upgrade Status (https://www.drupal.org/
   

   Plural of API is "APIs" - no apostrophe needed.

4. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +major-versions-eg-from-drupal-8-to-drupal-9 for details, and https://www.drupal
   +.org/docs/8/upgrade/known-issues-when-upgrading-from-drupal-6-or-7-to-drupal-8
   +for known issues.
   

   Is the 6/7 to 8 "known issues" page really relevant to an 8 to 9 upgrade? A quick scan doesn't show anything that jumps out as useful.

5. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +  * If you are upgrading to Drupal version x.y.z, then x is known as the major
   +    version number, y is known as the minor version number, and z is known as
   +    the patch version number. The download file will be named
   +    drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used
   +    only x.y (MAJOR.MINOR) to designate their versions.
   

   This seems a bit out of place, is this better off at the very top of the document? By "previous" versions it means 7 and before, we could make this clearer. Is this also worth keeping in UPDATE.txt?

6. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +  * All directories mentioned in this document are relative to the directory of
   +    your Drupal installation.
   

   No directories are mentioned in this document? This seems more relevant to UPDATE.txt, but it has been removed from there.

7. +++ b/core/MIGRATE.txt
   @@ -0,0 +1,78 @@
   +  * It is wise to try an update or upgrade on a test copy of your site before
   +    applying it to your live site. Even minor updates can cause your site's
   +    behavior to change.
   

   The "update or upgrade" text isn't relevant here. We already told the user to "test in a development environment" further up, though reiterating this is good. I don't think "minor updates" is relevant here either, as we are talking about major version migrations.

I'm good to keep working at this--but I'm still not sure if creating the migrate file is definitely what we want to do or not. #35 mentioned it as a possibility. Or, if it's the difference between "update" and "upgrade" should it be UPGRADE.txt? Mostly wondering because if we do use migrate, I imagine people will check it out expecting to find information on migrating sites instead of upgrading to D9. Thoughts?

We shouldn't put update/upgrade information into a file called MIGRATE.txt

There are a few ways the files could be re-organised though:

1. Merge UPGRADE.txt and UPDATE.txt into the same file. Covering patch, minor, and the different major updates including 6 and 7.

2. Have UPDATE.txt for patch/minor/major and MIGRATE.txt for 6 and 7

3. UPDATE.txt for patch/minor and UPGRADE.txt for major + migrate, although that seems more of an artificial grouping than 1 or 2.

I agree with catch. And of the options I prefer #3 because of the following text at the top of Upgrading to Drupal 8.

Upgrading a Drupal site means a change of a major version, for example from Drupal 6 to Drupal 8 or from Drupal 7 to Drupal 8. This documentation guide is about upgrading a Drupal 6 or Drupal 7 site to Drupal 8.

Updating a Drupal site means an update from one minor version to another, for example from '8.0.2' to '8.3.0'. Please refer to Updating a Drupal 8 site for more information on updating.

Those definitions came about from conversations where migrate maintainers worked to clarify the use of 'migrate', 'upgrade' and 'update', for the sake of our sanity and what to display to the user in the /upgrade form. It was also decided that 'upgrade' and 'update' are shown to the user (even if migrate is being used under the hood) and the terms migrate/migration etc. are reserved for documentation meant for developers only.

Hope that helps.

Also posted #3136302: Replace UPDATE.txt with links to d.o documentation as a possible solution, given time is getting very short prior to an RC. This would not preclude adding documentation back to the codebase itself later in this issue.

+1 to the addressing this with the issue proposed in #46. This has added benefits beyond removing a beta target critical from the queue:

• This document has to account for several use cases, which means there is going to be content that is not relevant to every user. A shorter document that refers users to the documentation specific to their needs means less overall noise and potential for confusion.
• Once more users get an opportunity to work with this release, we may discover that small changes in phrasing would provide a much better experience. This would allow us to make those changes quickly and without burdening committers.
• One of the concerns I imagine some may have about referencing online documentation is that it is surrendering a bit of control as the documents could change without the codebase realizing it. This is a reasonable concern and may still be the best long-term solution but as @catch said already, the online documentation approach does not preclude it being added to the codebase later, perhaps once we're out of the more turbulent early stages of a new release.

#3136302: Replace UPDATE.txt with links to d.o documentation is in. Can we close this as a duplicate?

FWIW as @bnjmnm pointed out to me, UPGRADE.txt does not exist and has not existed for years, unless this is supposed to be about patching Drupal 7. (If it is, we can just move this issue to 7.x I think, since 8.8.x has now been addressed.)

I agree with @xjm. Because #3136302: Replace UPDATE.txt with links to d.o documentation has landed, this issue is no longer relevant for Drupal 8.x and 9.x. Therefor moving the issue back to 7.x and removing the tag "beta target".

My apologies to everybody who worked hard on this issue.

Reading the issue summary and the first few comments this was always a Drupal 8 issue and not Drupal 7. So what to do with this? I guess this should go back to the Drupal 9 queue and then closed as a duplicate of #3136302: Replace UPDATE.txt with links to d.o documentation