Release: Use an in-repository dist README fixture

Use a dist README fixture kept in the jQuery repository instead of modifying
an existing one. This makes the jQuery repository the single source of truth
when it comes to jQuery releases and it makes it easier to make changes to
README without worrying how it will affect older jQuery lines.

The commit also ES6ifies build/release.js & build/release/dist.js

Closes gh-4614

diff --git a/build/fixtures/README.md b/build/fixtures/README.md
new file mode 100644 (file)
index 0000000..e52bde0
--- /dev/null
+++ b/build/fixtures/README.md
@@ -0,0 +1,62 @@
+# jQuery
+
+> jQuery is a fast, small, and feature-rich JavaScript library.
+
+For information on how to get started and how to use jQuery, please see [jQuery's documentation](http://api.jquery.com/).
+For source files and issues, please visit the [jQuery repo](https://github.com/jquery/jquery).
+
+If upgrading, please see the [blog post for @VERSION](@BLOG_POST_LINK). This includes notable differences from the previous version and a more readable changelog.
+
+## Including jQuery
+
+Below are some of the most common ways to include jQuery.
+
+### Browser
+
+#### Script tag
+
+```html
+<script src="https://code.jquery.com/jquery-@VERSION.min.js"></script>
+```
+
+#### Babel
+
+[Babel](http://babeljs.io/) is a next generation JavaScript compiler. One of the features is the ability to use ES6/ES2015 modules now, even though browsers do not yet support this feature natively.
+
+```js
+import $ from "jquery";
+```
+
+#### Browserify/Webpack
+
+There are several ways to use [Browserify](http://browserify.org/) and [Webpack](https://webpack.github.io/). For more information on using these tools, please refer to the corresponding project's documention. In the script, including jQuery will usually look like this...
+
+```js
+var $ = require( "jquery" );
+```
+
+#### AMD (Asynchronous Module Definition)
+
+AMD is a module format built for the browser. For more information, we recommend [require.js' documentation](http://requirejs.org/docs/whyamd.html).
+
+```js
+define( [ "jquery" ], function( $ ) {
+
+} );
+```
+
+### Node
+
+To include jQuery in [Node](nodejs.org), first install with npm.
+
+```sh
+npm install jquery
+```
+
+For jQuery to work in Node, a window with a document is required. Since no such window exists natively in Node, one can be mocked by tools such as [jsdom](https://github.com/tmpvar/jsdom). This can be useful for testing purposes.
+
+```js
+const { JSDOM } = require( "jsdom" );
+const { window } = new JSDOM( "" );
+const $ = require( "jquery" )( window );
+```

diff --git a/build/release.js b/build/release.js
index e0116d1605c183933b8e92176bb5694021c7839a..e0e042f80627dbd5847230973bdf64d7d7e33b76 100644 (file)
--- a/build/release.js
+++ b/build/release.js
@@ -4,23 +4,22 @@ var fs = require( "fs" );
 
 module.exports = function( Release ) {
 
-       var
-               distFiles = [
-                       "dist/jquery.js",
-                       "dist/jquery.min.js",
-                       "dist/jquery.min.map",
-                       "dist/jquery.slim.js",
-                       "dist/jquery.slim.min.js",
-                       "dist/jquery.slim.min.map"
-               ],
-               filesToCommit = [
-                       ...distFiles,
-                       "src/core.js"
-               ],
-               cdn = require( "./release/cdn" ),
-               dist = require( "./release/dist" ),
+       const distFiles = [
+               "dist/jquery.js",
+               "dist/jquery.min.js",
+               "dist/jquery.min.map",
+               "dist/jquery.slim.js",
+               "dist/jquery.slim.min.js",
+               "dist/jquery.slim.min.map"
+       ];
+       const filesToCommit = [
+               ...distFiles,
+               "src/core.js"
+       ];
+       const cdn = require( "./release/cdn" );
+       const dist = require( "./release/dist" );
 
-               npmTags = Release.npmTags;
+       const npmTags = Release.npmTags;
 
        function setSrcVersion( filepath ) {
                var contents = fs.readFileSync( filepath, "utf8" );
@@ -86,6 +85,7 @@ module.exports = function( Release ) {
 module.exports.dependencies = [
        "archiver@1.3.0",
        "shelljs@0.7.7",
+       "inquirer@7.0.4",
        "npm@4.4.1",
        "chalk@1.1.3"
 ];

diff --git a/build/release/dist.js b/build/release/dist.js
index e2b1c5fb44369e209a5d229cb46a473462e075dd..65e8d0eb0e9cfdfec0d9313b9ff2588bace84fa8 100644 (file)
--- a/build/release/dist.js
+++ b/build/release/dist.js
@@ -2,33 +2,33 @@
 
 module.exports = function( Release, files, complete ) {
 
-       var
-               fs = require( "fs" ),
-               shell = require( "shelljs" ),
-               pkg = require( Release.dir.repo + "/package.json" ),
-               distRemote = Release.remote
-
-                       // For local and github dists
-                       .replace( /jquery(\.git|$)/, "jquery-dist$1" ),
-
-               // These files are included with the distribution
-               extras = [
-                       "amd",
-                       "src",
-                       "LICENSE.txt",
-                       "AUTHORS.txt",
-                       "package.json"
-               ];
+       const fs = require( "fs" ).promises;
+       const shell = require( "shelljs" );
+       const inquirer = require( "inquirer" );
+       const pkg = require( `${ Release.dir.repo }/package.json` );
+       const distRemote = Release.remote
+
+               // For local and github dists
+               .replace( /jquery(\.git|$)/, "jquery-dist$1" );
+
+       // These files are included with the distribution
+       const extras = [
+               "amd",
+               "src",
+               "LICENSE.txt",
+               "AUTHORS.txt",
+               "package.json"
+       ];
 
        /**
         * Clone the distribution repo
         */
        function clone() {
                Release.chdir( Release.dir.base );
-               Release.dir.dist = Release.dir.base + "/dist";
+               Release.dir.dist = `${ Release.dir.base }/dist`;
 
                console.log( "Using distribution repo: ", distRemote );
-               Release.exec( "git clone " + distRemote + " " + Release.dir.dist,
+               Release.exec( `git clone ${ distRemote } ${ Release.dir.dist }`,
                        "Error cloning repo." );
 
                // Distribution always works on master
@@ -55,56 +55,60 @@ module.exports = function( Release, files, complete ) {
        /**
         * Replace the version in the README
         * @param {string} readme
+        * @param {string} blogPostLink
         */
-       function editReadme( readme ) {
-               var rprev = new RegExp( Release.prevVersion, "g" );
-               return readme.replace( rprev, Release.newVersion );
+       function editReadme( readme, blogPostLink ) {
+               return readme
+                       .replace( /@VERSION/g, Release.newVersion )
+                       .replace( /@BLOG_POST_LINK/g, blogPostLink );
        }
 
        /**
         * Copy necessary files over to the dist repo
         */
-       function copy() {
+       async function copy() {
 
                // Copy dist files
-               var distFolder = Release.dir.dist + "/dist",
-                       readme = fs.readFileSync( Release.dir.dist + "/README.md", "utf8" ),
-                       rmIgnore = files
-                               .concat( [
-                                       "README.md",
-                                       "node_modules"
-                               ] )
-                               .map( function( file ) {
-                                       return Release.dir.dist + "/" + file;
-                               } );
+               const distFolder = `${ Release.dir.dist }/dist`;
+               const readme = await fs.readFile(
+                       `${ Release.dir.repo }/build/fixtures/README.md`, "utf8" );
+               const rmIgnore = [ ...files, "node_modules" ]
+                       .map( file => `${ Release.dir.dist }/${ file }` );
 
                shell.config.globOptions = {
                        ignore: rmIgnore
                };
 
+               const { blogPostLink } = await inquirer.prompt( [ {
+                       type: "input",
+                       name: "blogPostLink",
+                       message: "Enter URL of the blog post announcing the jQuery release...\n"
+               } ] );
+
                // Remove extraneous files before copy
-               shell.rm( "-rf", Release.dir.dist + "/**/*" );
+               shell.rm( "-rf", `${ Release.dir.dist }/**/*` );
 
                shell.mkdir( "-p", distFolder );
                files.forEach( function( file ) {
-                       shell.cp( "-f", Release.dir.repo + "/" + file, distFolder );
+                       shell.cp( "-f", `${ Release.dir.repo }/${ file }`, distFolder );
                } );
 
                // Copy other files
                extras.forEach( function( file ) {
-                       shell.cp( "-rf", Release.dir.repo + "/" + file, Release.dir.dist );
+                       shell.cp( "-rf", `${ Release.dir.repo }/${ file }`, Release.dir.dist );
                } );
 
-               // Remove the wrapper from the dist repo
-               shell.rm( "-f", Release.dir.dist + "/src/wrapper.js" );
+               // Remove the wrapper & the ESLint config from the dist repo
+               shell.rm( "-f", `${ Release.dir.dist }/src/wrapper.js` );
+               shell.rm( "-f", `${ Release.dir.dist }/src/.eslintrc.json` );
 
                // Write generated bower file
-               fs.writeFileSync( Release.dir.dist + "/bower.json", generateBower() );
+               await fs.writeFile( `${ Release.dir.dist }/bower.json`, generateBower() );
 
-               fs.writeFileSync( Release.dir.dist + "/README.md", editReadme( readme ) );
+               await fs.writeFile( `${ Release.dir.dist }/README.md`,
+                       editReadme( readme, blogPostLink ) );
 
                console.log( "Files ready to add." );
-               console.log( "Edit the dist README.md to include the latest blog post link." );
        }
 
        /**
@@ -114,14 +118,14 @@ module.exports = function( Release, files, complete ) {
                console.log( "Adding files to dist..." );
                Release.exec( "git add -A", "Error adding files." );
                Release.exec(
-                       "git commit -m \"Release " + Release.newVersion + "\"",
+                       `git commit -m "Release ${ Release.newVersion }"`,
                        "Error committing files."
                );
                console.log();
 
                console.log( "Tagging release on dist..." );
-               Release.exec( "git tag " + Release.newVersion,
-                       "Error tagging " + Release.newVersion + " on dist repo." );
+               Release.exec( `git tag ${ Release.newVersion }`,
+                       `Error tagging ${ Release.newVersion } on dist repo.` );
                Release.tagTime = Release.exec( "git log -1 --format=\"%ad\"",
                        "Error getting tag timestamp." ).trim();
        }
@@ -133,9 +137,12 @@ module.exports = function( Release, files, complete ) {
                Release.chdir( Release.dir.dist );
 
                console.log( "Pushing release to dist repo..." );
-               Release.exec( "git push " + ( Release.isTest ? " --dry-run " : "" ) +
-                       distRemote + " master --tags",
-                       "Error pushing master and tags to git repo." );
+               Release.exec(
+                       `git push ${
+                               Release.isTest ? " --dry-run" : ""
+                       } ${ distRemote } master --tags`,
+                       "Error pushing master and tags to git repo."
+               );
 
                // Set repo for npm publish
                Release.dir.origRepo = Release.dir.repo;