Thoroughly review and update docs

CHANGELOG.md

@@ -4,13 +4,63 @@
 *unreleased*
 
 ### Breaking Changes
-* `preferConst` is now `output.preferConst`
+* Several (mostly deprecated) options have been removed or renamed (#2293, #2409):
+  - banner -> output.banner
+  - dest -> output.file
+  - entry -> input
+  - experimentalCodeSplitting -> now always active
+  - experimentalDynamicImport -> now always active
+  - experimentalPreserveModules -> preserveModules
+  - exports -> output.exports
+  - extend -> output.extend
+  - footer -> output.footer
+  - format -> output.format
+  - freeze -> output.freeze
+  - globals -> output.globals
+  - indent -> output.indent
+  - interop -> output.interop
+  - intro -> output.intro 
+  - load -> use plugin API
+  - moduleName -> output.name
+  - name -> output.name
+  - noConflict -> output.noConflict
+  - output.moduleId -> output.amd.id
+  - outro -> output.outro
+  - paths -> output.paths
+  - preferConst -> output.preferConst
+  - pureExternalModules -> treeshake.pureExternalModules
+  - resolveExternal -> use plugin API
+  - resolveId -> use plugin API
+  - sourcemap -> output.sourcemap
+  - sourceMap -> output.sourcemap
+  - sourceMapFile -> output.sourcemapFile
+  - strict -> output.strict
+  - targets -> use output as an array
+  - transform -> use plugin API
+  - useStrict -> output.strict
+* In general, output options can no longer be used as input options (#2409)
+* `bundle.generate` and `bundle.write` now return a new format (#2293)
+* Several plugin hooks have become deprecated and will display warnings when used (#2409):
+  - transformBundle
+  - transformChunk
+  - ongenerate
+  - onwrite
+* Plugin transform dependencies are deprecated in favour of the `watchChange` plugin hook (#2409)
+* Accessing `this.watcher` in plugin hooks is deprecated in favour of the `watchChange` plugin hook (#2409)
+* Using dynamic import statements will by default create a new chunk unless `inlineDynamicImports` is used (#2293)
+* Rollup now uses acorn@6 which means that acorn plugins must be compatible with this version; acorn is now external for non-browser builds to make plugins work (#2293)
 
 ### Features
+* The `--dir` ClI option can now be aliased as `-d` (#2293)
+* The `--input` option now supports named entry points via `=` (#2293)
+
 ### Bug Fixes
-* Both the `--input` option as well as the default CLI option now support named inputs
+* Both the `--input` option as well as the default CLI option now support named inputs (#2293)
 
 ### Pull Requests
+* [#2293](https://github.com/rollup/rollup/pull/2293): Unify code paths for 1.0 relase and update documentation (@guybedford and @lukastaegert)
+* [#2409](https://github.com/rollup/rollup/pull/2409): Remove old deprecated features and add new deprecation warnings (@guybedford)
+* [#2486](https://github.com/rollup/rollup/pull/2486): Upgrade to acorn 6 (@marijnh)
 
 ## 0.68.2
 *2018-12-23*

bin/src/help.md

@@ -5,32 +5,51 @@ Usage: rollup [options] <entry file>
 
 Basic options:
 
--v, --version               Show version number
--h, --help                  Show this help message
 -c, --config                Use this config file (if argument is used but value
                               is unspecified, defaults to rollup.config.js)
--w, --watch                 Watch files in bundle and rebuild on changes
--i, --input                 Input (alternative to <entry file>)
--o, --file <output>         Output (if absent, prints to stdout)
--f, --format [es]           Type of output (amd, cjs, es, iife, umd)
+-d, --dir                   Directory for chunks (if absent, prints to stdout)
 -e, --external              Comma-separate list of module IDs to exclude
--g, --globals               Comma-separate list of `module ID:Global` pairs
-                              Any module IDs defined here are added to external
--n, --name                  Name for UMD export
+-f, --format <format>       Type of output (amd, cjs, esm, iife, umd)
+-g, --globals               Comma-separate list of `moduleID:Global` pairs
+-h, --help                  Show this help message
+-i, --input                 Input (alternative to <entry file>)
 -m, --sourcemap             Generate sourcemap (`-m inline` for inline map)
---amd.id                    ID for AMD module (default is anonymous)
---amd.define                Function to use in place of `define`
---no-strict                 Don't emit a `"use strict";` in the generated modules.
---no-indent                 Don't indent result
+-n, --name                  Name for UMD export
+-o, --file <output>         Single output file (if absent, prints to stdout)
+-v, --version               Show version number
+-w, --watch                 Watch files in bundle and rebuild on changes
+--amd.id <id>               ID for AMD module (default is anonymous)
+--amd.define <name>         Function to use in place of `define`
+--assetFileNames <pattern>  Name pattern for emitted assets
+--banner <text>             Code to insert at top of bundle (outside wrapper)
+--chunkFileNames <pattern>  Name pattern for emitted secondary chunks
+--compact                   Minify wrapper code
+--context <variable>        Specify top-level `this` value
+--entryFileNames <pattern>  Name pattern for emitted entry chunks
 --environment <values>      Settings passed to config file (see example)
---no-conflict               Generate a noConflict method for UMD globals
---no-treeshake              Disable tree-shaking
---silent                    Don't print warnings
---intro                     Content to insert at top of bundle (inside wrapper)
---outro                     Content to insert at end of bundle (inside wrapper)
---banner                    Content to insert at top of bundle (outside wrapper)
---footer                    Content to insert at end of bundle (outside wrapper)
+--no-esModule               Do not add __esModule property
+--exports <mode>            Specify export mode (auto, default, named, none)
+--extend                    Extend global variable defined by --name
+--footer <text>             Code to insert at end of bundle (outside wrapper)
+--no-freeze                 Do not freeze namespace objects
+--no-indent                 Don't indent result
 --no-interop                Do not include interop block
+--inlineDynamicImports      Create single bundle when using dynamic imports
+--intro <text>              Code to insert at top of bundle (inside wrapper)
+--namespaceToStringTag      Create proper `.toString` methods for namespaces
+--noConflict                Generate a noConflict method for UMD globals
+--no-strict                 Don't emit `"use strict";` in the generated modules
+--outro <text>              Code to insert at end of bundle (inside wrapper)
+--preferConst               Use `const` instead of `var` for exports
+--preserveModules           Preserve module structure
+--preserveSymlinks          Do not follow symlinks when resolving files
+--shimMissingExports        Create shim variables for missing exports
+--silent                    Don't print warnings
+--sourcemapExcludeSources   Do not include source code in source maps
+--sourcemapFile <file>      Specify bundle position for source maps
+--no-treeshake              Disable tree-shaking optimisations
+--no-treeshake.propertyReadSideEffects Ignore property access side-effects
+--treeshake.pureExternalModules        Assume side-effect free externals
 
 Examples:
 

docs/00-introduction.md

@@ -4,7 +4,7 @@ title: Introduction
 
 ### Overview
 
-Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application. It uses the new standardized format for code modules included in the ES6 revision of JavaScript, instead of previous idiosyncratic solutions such as CommonJS and AMD. ES6 modules let you freely and seamlessly combine the most useful individual functions from your favorite libraries. This will eventually be possible natively, but Rollup lets you do it today.
+Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application. It uses the new standardized format for code modules included in the ES6 revision of JavaScript, instead of previous idiosyncratic solutions such as CommonJS and AMD. ES modules let you freely and seamlessly combine the most useful individual functions from your favorite libraries. This will eventually be possible natively everywhere, but Rollup lets you do it today.
 
 ### Quick start
 
@@ -41,11 +41,11 @@ $ rollup main.js --file bundle.js --format umd --name "myBundle"
 
 Developing software is usually easier if you break your project into smaller separate pieces, since that often removes unexpected interactions and dramatically reduces the complexity of the problems you'll need to solve, and simply writing smaller projects in the first place [isn't necessarily the answer](https://medium.com/@Rich_Harris/small-modules-it-s-not-quite-that-simple-3ca532d65de4). Unfortunately, JavaScript has not historically included this capability as a core feature in the language.
 
-This finally changed with the ES6 revision of JavaScript, which includes a syntax for importing and exporting functions and data so they can be shared between separate scripts. The specification is now fixed, but it is not yet implemented in browsers or Node.js. Rollup allows you to write your code using the new module system, and will then compile it back down to existing supported formats such as CommonJS modules, AMD modules, and IIFE-style scripts. This means that you get to *write future-proof code*, and you also get the tremendous benefits of...
+This finally changed with the ES6 revision of JavaScript, which includes a syntax for importing and exporting functions and data so they can be shared between separate scripts. The specification is now fixed, but it is only implemented in modern browsers and not finalised in Node.js. Rollup allows you to write your code using the new module system, and will then compile it back down to existing supported formats such as CommonJS modules, AMD modules, and IIFE-style scripts. This means that you get to *write future-proof code*, and you also get the tremendous benefits of...
 
 ### Tree-Shaking
 
-In addition to enabling the use of ES6 modules, Rollup also statically analyzes the code you are importing, and will exclude anything that isn't actually used. This allows you to build on top of existing tools and modules without adding extra dependencies or bloating the size of your project.
+In addition to enabling the use of ES modules, Rollup also statically analyzes the code you are importing, and will exclude anything that isn't actually used. This allows you to build on top of existing tools and modules without adding extra dependencies or bloating the size of your project.
 
 For example, with CommonJS, the *entire tool or library must be imported*.
 
@@ -57,7 +57,7 @@ const query = 'Rollup';
 utils.ajax(`https://api.example.com?search=${query}`).then(handleResponse);
 ```
 
-But with ES6 modules, instead of importing the whole `utils` object, we can just import the one `ajax` function we need:
+But with ES modules, instead of importing the whole `utils` object, we can just import the one `ajax` function we need:
 
 ```js
 // import the ajax function with an ES6 import statement
@@ -67,7 +67,7 @@ const query = 'Rollup';
 ajax(`https://api.example.com?search=${query}`).then(handleResponse);
 ```
 
-Because Rollup includes the bare minimum, it results in lighter, faster, and less complicated libraries and applications. Since this approach is based on explicit `import` and `export` statements, it is more effective than simply running an automated minifier to detect unused variables in the compiled output code.
+Because Rollup includes the bare minimum, it results in lighter, faster, and less complicated libraries and applications. Since this approach can utilise explicit `import` and `export` statements, it is more effective than simply running an automated minifier to detect unused variables in the compiled output code.
 
 
 ### Compatibility
@@ -76,12 +76,6 @@ Because Rollup includes the bare minimum, it results in lighter, faster, and les
 
 Rollup can import existing CommonJS modules [through a plugin](https://github.com/rollup/rollup-plugin-commonjs).
 
-#### Publishing ES6 Modules
-
-To make sure your ES6 modules are immediately usable by tools that work with CommonJS such as Node.js and webpack, you can use Rollup to compile to UMD or CommonJS format, and then point to that compiled version with the `main` property in your `package.json` file. If your `package.json` file also has a `module` field, ES6-aware tools like Rollup and [webpack 2+](https://webpack.js.org/) will [import the ES6 module version](https://github.com/rollup/rollup/wiki/pkg.module) directly.
-
-### Links
-
-- step-by-step [tutorial video series](https://code.lengstorf.com/learn-rollup-js/), with accompanying written walkthrough
-- miscellaneous issues in the [wiki](https://github.com/rollup/rollup/wiki)
+#### Publishing ES Modules
 
+To make sure your ES modules are immediately usable by tools that work with CommonJS such as Node.js and webpack, you can use Rollup to compile to UMD or CommonJS format, and then point to that compiled version with the `main` property in your `package.json` file. If your `package.json` file also has a `module` field, ESM-aware tools like Rollup and [webpack 2+](https://webpack.js.org/) will [import the ES module version](https://github.com/rollup/rollup/wiki/pkg.module) directly.

docs/01-command-line-reference.md

@@ -8,7 +8,7 @@ Rollup should typically be used from the command line. You can provide an  optio
 
 Rollup configuration files are optional, but they are powerful and convenient and thus **recommended**.
 
-A config file is an ES6 module that exports a default object with the desired options. Typically, it is called `rollup.config.js` and sits in the root directory of your project.
+A config file is an ES module that exports a default object with the desired options. Typically, it is called `rollup.config.js` and sits in the root directory of your project.
 
 Also you can use CJS modules syntax for the config file.
 
@@ -31,66 +31,75 @@ Consult the [big list of options](guide/en#big-list-of-options) for details on e
 
 export default { // can be an array (for multiple inputs)
   // core input options
-  input,     // required
   external,
+  input, // required
   plugins,
 
   // advanced input options
+  cache,
+  inlineDynamicImports,
+  manualChunks,
   onwarn,
-  perf,
+  preserveModules,
 
   // danger zone
   acorn,
   acornInjectPlugins,
-  treeshake,
   context,
   moduleContext,
+  preserveSymlinks,
+  shimMissingExports,
+  treeshake,
 
   // experimental
-  experimentalCodeSplitting,
-  manualChunks,
-  experimentalOptimizeChunks,
   chunkGroupingSize,
+  experimentalCacheExpiry,
+  experimentalOptimizeChunks,
+  experimentalTopLevelAwait,
+  perf,
 
-  output: {  // required (can be an array, for multiple outputs)
+  output: { // required (can be an array, for multiple outputs)
     // core output options
-    format,  // required
-    file,
     dir,
-    name,
+    file,
+    format, // required
     globals,
+    name,
 
     // advanced output options
-    paths,
+    assetFileNames,
     banner,
+    chunkFileNames,
+    compact,
+    entryFileNames,
+    extend,
     footer,
+    interop,
     intro,
     outro,
+    paths,
     sourcemap,
+    sourcemapExcludeSources,
     sourcemapFile,
     sourcemapPathTransform,
-    interop,
-    extend,
 
     // danger zone
-    exports,
     amd,
-    indent,
-    strict,
+    esModule,
+    exports,
     freeze,
+    indent,
     namespaceToStringTag,
-
-    // experimental
-    entryFileNames,
-    chunkFileNames,
-    assetFileNames
+    noConflict,
+    preferConst,
+    strict
   },
 
   watch: {
     chokidar,
-    include,
+    clearScreen,
     exclude,
-    clearScreen
+    include
   }
 };
 ```
@@ -125,7 +134,7 @@ If you want to create your config asynchronously, Rollup can also handle a `Prom
 
 ```javascript
 // rollup.config.js
-import fetch from  'node-fetch';
+import fetch from 'node-fetch';
 export default fetch('/some-remote-service-or-file-which-returns-actual-config');
 ```
 
@@ -179,26 +188,44 @@ Many options have command line equivalents. Any arguments passed here will overr
 ```text
 -c, --config                Use this config file (if argument is used but value
                               is unspecified, defaults to rollup.config.js)
--i, --input                 Input (alternative to <entry file>)
--o, --file <output>         Output (if absent, prints to stdout)
--f, --format [esm]          Type of output (amd, cjs, esm, iife, umd)
+-d, --dir                   Directory for chunks (if absent, prints to stdout)
 -e, --external              Comma-separate list of module IDs to exclude
--g, --globals               Comma-separate list of `module ID:Global` pairs
-                              Any module IDs defined here are added to external
--n, --name                  Name for UMD export
+-f, --format <format>       Type of output (amd, cjs, esm, iife, umd)
+-g, --globals               Comma-separate list of `moduleID:Global` pairs
+-i, --input                 Input (alternative to <entry file>)
 -m, --sourcemap             Generate sourcemap (`-m inline` for inline map)
---amd.id                    ID for AMD module (default is anonymous)
---amd.define                Function to use in place of `define`
---no-strict                 Don't emit a `"use strict";` in the generated modules.
+-n, --name                  Name for UMD export
+-o, --file <output>         Single output file (if absent, prints to stdout)
+--amd.id <id>               ID for AMD module (default is anonymous)
+--amd.define <name>         Function to use in place of `define`
+--assetFileNames <pattern>  Name pattern for emitted assets
+--banner <text>             Code to insert at top of bundle (outside wrapper)
+--chunkFileNames <pattern>  Name pattern for emitted secondary chunks
+--compact                   Minify wrapper code
+--context <variable>        Specify top-level `this` value
+--entryFileNames <pattern>  Name pattern for emitted entry chunks
+--no-esModule               Do not add __esModule property
+--exports <mode>            Specify export mode (auto, default, named, none)
+--extend                    Extend global variable defined by --name
+--footer <text>             Code to insert at end of bundle (outside wrapper)
+--no-freeze                 Do not freeze namespace objects
 --no-indent                 Don't indent result
---environment <values>      Environment variables passed to config file
---noConflict                Generate a noConflict method for UMD globals
---no-treeshake              Disable tree-shaking
---intro                     Content to insert at top of bundle (inside wrapper)
---outro                     Content to insert at end of bundle (inside wrapper)
---banner                    Content to insert at top of bundle (outside wrapper)
---footer                    Content to insert at end of bundle (outside wrapper)
 --no-interop                Do not include interop block
+--inlineDynamicImports      Create single bundle when using dynamic imports
+--intro <text>              Code to insert at top of bundle (inside wrapper)
+--namespaceToStringTag      Create proper `.toString` methods for namespaces
+--noConflict                Generate a noConflict method for UMD globals
+--no-strict                 Don't emit `"use strict";` in the generated modules
+--outro <text>              Code to insert at end of bundle (inside wrapper)
+--preferConst               Use `const` instead of `var` for exports
+--preserveModules           Preserve module structure
+--preserveSymlinks          Do not follow symlinks when resolving files
+--shimMissingExports        Create shim variables for missing exports
+--sourcemapExcludeSources   Do not include source code in source maps
+--sourcemapFile <file>      Specify bundle position for source maps
+--no-treeshake              Disable tree-shaking optimisations
+--no-treeshake.propertyReadSideEffects Ignore property access side-effects
+--treeshake.pureExternalModules        Assume side-effect free externals
 ```
 
 In addition, the following arguments can be used: