All: clarify version support; upgrade guide content; new download button

Ref jquery/jquery-wp-content#462
Ref gh-245
Fixes gh-243
Closes gh-246

Co-authored-by: Andre Angelantoni <[email protected]>

Author: timmywil

pages/download.md

@@ -26,14 +26,14 @@ Browse the jQuery CDN at **[releases.jquery.com](https://releases.jquery.com)**
 
 ### Upgrade
 
-For help when upgrading jQuery, read the [upgrade guide](/upgrade-guide/).
-We also recommend using the [jQuery Migrate plugin](https://github.com/jquery/jquery-migrate)
+For help when upgrading jQuery, read the [upgrade guides](/upgrade-guide/).
+We also recommend using the [jQuery Migrate plugin](https://github.com/jquery/jquery-migrate).
 
 ### jQuery Migrate Plugin
 
 The [jQuery Migrate plugin](https://github.com/jquery/jquery-migrate/#readme) simplifies upgrading from older versions of jQuery. The plugin restores deprecated features and behaviors so that older code will still run properly on newer versions of jQuery.
 
-When upgrading from a pre-1.9 jQuery version to jQuery 1.9 or upto jQuery 3.0, first use jQuery Migrate 1.x:
+When upgrading from a pre-1.9 jQuery version to jQuery 1.9 or up to jQuery 3.0, first use jQuery Migrate 1.x:
 
 * <a href="https://code.jquery.com/jquery-migrate-1.4.1.min.js">Download jQuery Migrate 1.4.1</a> (compressed production version)
 * <a href="https://code.jquery.com/jquery-migrate-1.4.1.js">Download the uncompressed, development jQuery Migrate 1.4.1</a>
@@ -43,11 +43,12 @@ When migrating from jQuery 3.x to a later jQuery 3.x version, use jQuery Migrate
 * <a href="https://code.jquery.com/jquery-migrate-3.5.0.min.js">Download jQuery Migrate 3.5.0</a> (compressed production version)
 * <a href="https://code.jquery.com/jquery-migrate-3.5.0.js">Download the uncompressed, development jQuery Migrate 3.5.0</a>
 
-Use the _compressed production_ version to simply restore compatibility issues without changing any application code.
+Use the _compressed production_ version to restore compatibility issues without changing any application code.
 
 Use the _uncompressed development_ version to additionally diagnose and help migrate compatibility issues, through helpful warnings on the console that identify how to transition your application code.
 
 ## Downloading jQuery using npm or Yarn
+
 jQuery is published on [npm](https://www.npmjs.com/) under the [jquery package](https://www.npmjs.com/package/jquery). You can install the latest version of jQuery with the npm CLI:
 ```
 npm install jquery

pages/index.html

@@ -2,23 +2,26 @@
 	"title": "jQuery",
 	"pageTemplate": "page-fullwidth.php",
 	"customFields": [
-			{ "key": "hide_title", "value": 1 }
+		{ "key": "hide_title", "value": 1 }
 	]
 }</script>
 
 <div id="banner-secondary" class="row">
-	<div class="downloads-box four columns push-eight">
-		<div class="download-main">
-			<a href="/download/" class="button large">
-				<span class="download"></span>
-				Download jQuery
-				<span>v3.7.1</span>
-				<span class="support-notice">The 1.x and 2.x branches no longer receive patches.</span>
-			</a>
-			<div class="download-options">
-				<a href="https://github.com/jquery/jquery">View Source on GitHub →</a>
-				<a href="https://learn.jquery.com/about-jquery/how-jquery-works/">How jQuery Works →</a>
-			</div>
+	<div class="download four columns push-eight">
+		<a href="/download/" class="button large">
+			<span class="download-button-content">
+				<span class="download-icon"></span>
+				<span class="download-message">
+					<span>Download jQuery</span>
+					<span class="download-version">v3.7.1</span>
+				</span>
+			</span>
+		</a>
+		<div class="download-options">
+			<div class="support-notice">Only the latest version of jQuery is supported.</div>
+			<a href="/support">Discover Support Options</a>
+			<a href="https://github.com/jquery/jquery">View Source on GitHub →</a>
+			<a href="https://learn.jquery.com/about-jquery/how-jquery-works/">How jQuery Works →</a>
 		</div>
 	</div>
 	<div class="features-box row eight columns pull-four">

pages/support.md

@@ -4,6 +4,22 @@
 }
 </script>
 
+## Supported versions
+
+We support only the latest version of jQuery. The 1.x and 2.x branches are no longer supported.
+
+jQuery 3.x is the current version branch of jQuery.
+
+jQuery 4.0 is in beta. Once jQuery 4.0 is released, we will provide security patches and bug fixes on the 3.x branch for a limited time.
+
+### Unsupported versions
+
+When using a version earlier than the latest version, there are a few options:
+
+* [Upgrade](/download#upgrade) to the latest version of jQuery. The best solution is to upgrade as it will include all features, bug fixes, security patches, and improvements. The [jQuery Migrate Plugin](https://github.com/jquery/jquery-migrate) and [upgrade guides](/upgrade-guide) are available to assist with upgrading.
+* Continue using an older version of jQuery, but include all security patches through [commercial security support](#commercial-support).
+* Continue using an older version of jQuery without security patches. **However, this can come with multiple risks.**
+
 ## Community support
 
 The following learning resources are available online and free of charge:
@@ -27,17 +43,11 @@ We are on [Libera Chat IRC](https://libera.chat/) in the `#jquery` channel where
 
 StackOverflow is a great place to ask questions and find support for all jQuery projects. Search or create [questions tagged with "jquery"](https://stackoverflow.com/questions/tagged/jquery), or refer to the ["jquery" tag introduction](https://stackoverflow.com/tags/jquery/info).
 
-### Archives
-
-* [Freenode IRC chat channels](https://irc.jquery.org/) (2011-2021)
-* [jQuery Forum](https://forum.jquery.com/) (2010-2021): For questions and advice regarding jQuery Core, jQuery UI, Themeroller, QUnit, development of jQuery Plugins, and more.
-* [jQuery Accessibility mailing list](https://groups.google.com/group/jquery-a11y) (2008-2016).
-
 ## Commercial support
 
 The following companies offer commercial support services for jQuery.
 
-* **[Bocoup](https://bocoup.com/)** builds complex cross device and cross platform JavaScript software for startups, the Fortune 500, and federally funded education projects. Bocoup offers in-depth JavaScript training on a number of subjects including jQuery. Learn more at <https://bocoup.com/services/training> or contact at <https://bocoup.com/contact>.
+[HeroDevs](https://www.herodevs.com/support/jquery-nes?utm_source=jQuery&utm_medium=link&utm_campaign=eol_support_jQuery) offers security and compatibility support for EOL versions of jQuery through the [OpenJS Ecosystem Sustainability Program](https://openjsf.org/ecosystem-sustainability-program) and is an approved commercial support vendor. Find out more about their [Never Ending Support options](https://www.herodevs.com/support/jquery-nes?utm_source=jQuery&utm_medium=link&utm_campaign=eol_support_jQuery).
 
 -------
 
@@ -72,3 +82,12 @@ For guidance on branding and trademark usage, visit <https://brand.jquery.org/>.
 For reporting bugs in libraries, documentation, or content, the project's GitHub issue tracker should be used. All jQuery projects can be found at https://github.com/jquery
 
 Still haven't found what you're looking for? Please feel free to contact: [[email protected]](mailto:[email protected])
+
+-------
+
+## Archives
+
+* [Freenode IRC chat channels](https://irc.jquery.org/) (2011-2021)
+* [jQuery Forum](https://forum.jquery.com/) (2010-2021): For questions and advice regarding jQuery Core, jQuery UI, Themeroller, QUnit, development of jQuery Plugins, and more.
+* [jQuery Accessibility mailing list](https://groups.google.com/group/jquery-a11y) (2008-2016).
+

pages/upgrade-guide.md

@@ -3,8 +3,35 @@
 	"noHeadingLinks": true
 }</script>
 
-## [3.5 Upgrade Guide](/upgrade-guide/3.5/)
+## jQuery Upgrade Guides
 
-## [3.0 Upgrade Guide](/upgrade-guide/3.0/)
+The jQuery upgrade guides provide information on all breaking changes and some notable changes in pinnacle versions of jQuery. Overall, jQuery has had very strong backwards compatibility throughout its history. However, these breaking changes were deemed necessary to address security concerns, fix bugs that could not be fixed without behavior changes, or to adapt to the introduction of modern APIs on the web. Most of the breaking changes listed should not apply to the majority of users, but these guides add some context and explanation for each change.
 
-## [1.9 Upgrade Guide](/upgrade-guide/1.9/)
+### [3.5 Upgrade Guide](/upgrade-guide/3.5/)
+
+### [3.0 Upgrade Guide](/upgrade-guide/3.0/)
+
+### [1.9 Upgrade Guide](/upgrade-guide/1.9/)
+
+### Upgrading jQuery
+
+The jQuery Team provides the [jQuery Migrate plugin](https://github.com/jquery/jquery-migrate) to make upgrading jQuery as easy as possible. It is mainly meant as a development tool that generates warning messages in the browser console that can be used to identify and fix compatibility issues. It temporarily restores deprecated features and behaviors so that older code will still run on newer versions of jQuery while the compatibility issues are addressed.
+
+There are two versions of jQuery Migrate: [1.x](https://github.com/jquery/jquery-migrate/tree/1.x-stable) and [3.x](https://github.com/jquery/jquery-migrate) (there is no Migrate 2.x). Only one version should be used at a time, but you may need to use both in succession if upgrading from a jQuery version that predates jQuery 1.9.
+
+For example, if your current jQuery version is 1.4.4, first upgrade to jQuery 1.12.4 with jQuery Migrate 1.x and then upgrade to the latest jQuery with jQuery Migrate 3.x. If your current version is 1.9 or later, you can update straight to the latest jQuery with jQuery Migrate 3.x.
+
+#### Using jQuery Migrate
+
+First, add jQuery Migrate to your page *after* loading jQuery.
+
+```html
+<script src="https://code.jquery.com/jquery-3.7.1.js"></script>
+<script src="https://code.jquery.com/jquery-migrate-3.4.1.js"></script>
+```
+
+Then, test your website or application. As different jQuery APIs are used, jQuery Migrate will log messages to the console warning about any deprecations or breaking changes. Address each warning one at a time.
+
+Finally, when no more warnings are logged to the console and all breaking changes have been addressed, the jQuery Migrate can be removed and migration is complete!
+
+See the [jQuery Migrate README](https://github.com/jquery/jquery-migrate) for more details.