Merge pull request #716 from WordPress/update/import-roots

Change import behavior to distinguish internal, WordPress, and external dependencies

blocks/components/editable/format-toolbar.js

@@ -1,10 +1,8 @@
 /**
- * Internal dependencies
+ * WordPress dependencies
  */
- // TODO: We mustn't import by relative path traversing from blocks to editor
- // as we're doing here; instead, we should consider a common components path.
-import IconButton from '../../../editor/components/icon-button';
-import Toolbar from '../../../editor/components/toolbar';
+import IconButton from 'editor/components/icon-button';
+import Toolbar from 'editor/components/toolbar';
 
 const FORMATTING_CONTROLS = [
 	{

blocks/components/editable/index.js

@@ -7,15 +7,17 @@ import { nodeListToReact } from 'dom-react';
 import { Fill } from 'react-slot-fill';
 import 'element-closest';
 
+/**
+ * WordPress dependencies
+ */
+import Toolbar from 'editor/components/toolbar';
+
 /**
  * Internal dependencies
  */
 import './style.scss';
 import FormatToolbar from './format-toolbar';
 import TinyMCE from './tinymce';
- // TODO: We mustn't import by relative path traversing from blocks to editor
- // as we're doing here; instead, we should consider a common components path.
-import Toolbar from '../../../editor/components/toolbar';
 
 const KEYCODE_BACKSPACE = 8;
 

blocks/library/button/index.js

@@ -1,10 +1,14 @@
+/**
+ * WordPress dependencies
+ */
+import IconButton from 'editor/components/icon-button';
+
 /**
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query } from 'api';
-import Editable from 'components/editable';
-import IconButton from '../../../editor/components/icon-button';
+import { registerBlock, query } from '../../api';
+import Editable from '../../components/editable';
 
 const { attr, children } = query;
 

blocks/library/embed/index.js

@@ -1,11 +1,14 @@
+/**
+ * WordPress dependencies
+ */
+import Dashicon from 'editor/components/dashicon';
+import Button from 'editor/components/button';
+
 /**
  * Internal dependencies
  */
-import { registerBlock, query } from 'api';
-import Editable from 'components/editable';
-// TODO: Revisit when we have a common components solution
-import Dashicon from '../../../editor/components/dashicon';
-import Button from '../../../editor/components/button';
+import { registerBlock, query } from '../../api';
+import Editable from '../../components/editable';
 
 const { attr, children } = query;
 

blocks/library/freeform/index.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { registerBlock, query, setUnknownTypeHandler } from 'api';
+import { registerBlock, query, setUnknownTypeHandler } from '../../api';
 
 const { html } = query;
 

blocks/library/heading/index.js

@@ -2,8 +2,8 @@
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query } from 'api';
-import Editable from 'components/editable';
+import { registerBlock, query } from '../../api';
+import Editable from '../../components/editable';
 
 const { children, prop } = query;
 

blocks/library/image/index.js

@@ -1,12 +1,15 @@
+/**
+ * WordPress dependencies
+ */
+import Dashicon from 'editor/components/dashicon';
+import Button from 'editor/components/button';
+
 /**
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query } from 'api';
-import Editable from 'components/editable';
-// TODO: Revisit when we have a common components solution
-import Dashicon from '../../../editor/components/dashicon';
-import Button from '../../../editor/components/button';
+import { registerBlock, query } from '../../api';
+import Editable from '../../components/editable';
 
 const { attr, children } = query;
 

blocks/library/list/index.js

@@ -2,8 +2,8 @@
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query as hpq } from 'api';
-import Editable from 'components/editable';
+import { registerBlock, query as hpq } from '../../api';
+import Editable from '../../components/editable';
 
 const { children, prop } = hpq;
 

blocks/library/pullquote/index.js

@@ -2,8 +2,8 @@
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query as hpq } from 'api';
-import Editable from 'components/editable';
+import { registerBlock, query as hpq } from '../../api';
+import Editable from '../../components/editable';
 
 const { children, query } = hpq;
 

blocks/library/quote/index.js

@@ -2,8 +2,8 @@
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock, query as hpq } from 'api';
-import Editable from 'components/editable';
+import { registerBlock, query as hpq } from '../../api';
+import Editable from '../../components/editable';
 
 const { children, query } = hpq;
 

blocks/library/separator/index.js

@@ -2,7 +2,7 @@
  * Internal dependencies
  */
 import './style.scss';
-import { registerBlock } from 'api';
+import { registerBlock } from '../../api';
 
 registerBlock( 'core/separator', {
 	title: wp.i18n.__( 'Separator' ),

blocks/library/text/index.js

@@ -1,8 +1,8 @@
 /**
  * Internal dependencies
  */
-import { registerBlock, query } from 'api';
-import Editable from 'components/editable';
+import { registerBlock, createBlock, query } from '../../api';
+import Editable from '../../components/editable';
 
 const { children } = query;
 
@@ -42,7 +42,7 @@ registerBlock( 'core/text', {
 				onFocus={ setFocus }
 				onSplit={ ( before, after ) => {
 					setAttributes( { content: before } );
-					insertBlockAfter( wp.blocks.createBlock( 'core/text', {
+					insertBlockAfter( createBlock( 'core/text', {
 						content: after
 					} ) );
 				} }

docs/coding-guidelines.md

@@ -31,3 +31,50 @@ For optional variations of an element or its descendants, you may use a modifier
 In all of the above cases, except in separating the top-level element from its descendants, you **must** use dash delimiters when expressing multiple terms of a name.
 
 You may observe that these conventions adhere closely to the [BEM (Blocks, Elements, Modifiers)](http://getbem.com/introduction/) CSS methodology, with minor adjustments to the application of modifiers.
+
+## JavaScript
+
+### Imports
+
+In the Gutenberg project, we use [the ES2015 import syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) to enable us to create modular code with clear separations between code of a specific feature, code shared across distinct WordPress features, and third-party dependencies.
+
+These separations are identified by multi-line comments at the top of a file which imports code from another file or source.
+
+#### External Dependencies
+
+An external dependency is third-party code that is not maintained by WordPress contributors, but instead [included in WordPress as a default script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-included-and-registered-by-wordpress) or referenced from an outside package manager like [npm](https://www.npmjs.com/).
+
+Example:
+
+```js
+/**
+ * External dependencies
+ */
+import TinyMCE from 'tinymce';
+```
+
+#### WordPress Dependencies
+
+To encourage reusability between features, our JavaScript is split into domain-specific modules which [`export`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export) one or more functions or objects. In the Gutenberg project, we've distinguished these modules under top-level directories `blocks`, `components`, `editor`, `element`, and `i18n`. These each serve an independent purpose, and often code is shared between them. For example, in order to localize its text, editor code will need to include functions from the `i18n` module.
+
+Example:
+
+```js
+/**
+ * WordPress dependencies
+ */
+import { __ } from 'i18n';
+```
+
+#### Internal Dependencies
+
+Within a specific feature, code is organized into separate files and folders. As is the case with external and WordPress dependencies, you can bring this code into scope by using the `import` keyword. The main distinction here is that when importing internal files, you should use relative paths specific to top-level directory you're working in.
+
+Example:
+
+```js
+/**
+ * Internal dependencies
+ */
+import VisualEditor from '../visual-editor';
+```

editor/components/block-mover/index.js

@@ -8,7 +8,7 @@ import { first, last } from 'lodash';
  * Internal dependencies
  */
 import './style.scss';
-import IconButton from 'components/icon-button';
+import IconButton from '../icon-button';
 
 function BlockMover( { onMoveUp, onMoveDown, isFirst, isLast } ) {
 	return (

editor/components/block-switcher/index.js

@@ -9,7 +9,7 @@ import clickOutside from 'react-click-outside';
  * Internal dependencies
  */
 import './style.scss';
-import IconButton from 'components/icon-button';
+import IconButton from '../icon-button';
 
 class BlockSwitcher extends wp.element.Component {
 	constructor() {

editor/components/inserter/index.js

@@ -7,7 +7,7 @@ import clickOutside from 'react-click-outside';
  * Internal dependencies
  */
 import InserterMenu from './menu';
-import IconButton from 'components/icon-button';
+import IconButton from '../icon-button';
 
 class Inserter extends wp.element.Component {
 	constructor() {

editor/components/inserter/menu.js

@@ -8,7 +8,7 @@ import { flow } from 'lodash';
  * Internal dependencies
  */
 import './style.scss';
-import Dashicon from 'components/dashicon';
+import Dashicon from '../dashicon';
 
 class InserterMenu extends wp.element.Component {
 	constructor() {

editor/components/toolbar/index.js

@@ -7,7 +7,7 @@ import classNames from 'classnames';
  * Internal dependencies
  */
 import './style.scss';
-import IconButton from 'components/icon-button';
+import IconButton from '../icon-button';
 
 function Toolbar( { controls } ) {
 	if ( ! controls || ! controls.length ) {

editor/header/mode-switcher/index.js

@@ -7,7 +7,7 @@ import { connect } from 'react-redux';
  * Internal dependencies
  */
 import './style.scss';
-import Dashicon from 'components/dashicon';
+import Dashicon from '../../components/dashicon';
 
 /**
  * Set of available mode options.

editor/header/tools/publish-button.js

@@ -6,8 +6,8 @@ import { connect } from 'react-redux';
 /**
  * Internal dependencies
  */
-import Button from 'components/button';
-import { savePost } from 'actions';
+import Button from '../../components/button';
+import { savePost } from '../../actions';
 
 function PublishButton( {
 	post,

editor/layout/index.js

@@ -8,10 +8,10 @@ import classnames from 'classnames';
  * Internal dependencies
  */
 import './style.scss';
-import Header from 'header';
-import Sidebar from 'sidebar';
-import TextEditor from 'modes/text-editor';
-import VisualEditor from 'modes/visual-editor';
+import Header from '../header';
+import Sidebar from '../sidebar';
+import TextEditor from '../modes/text-editor';
+import VisualEditor from '../modes/visual-editor';
 
 function Layout( { mode, isSidebarOpened } ) {
 	const className = classnames( 'editor-layout', {

editor/modes/text-editor/index.js

@@ -8,7 +8,7 @@ import Textarea from 'react-autosize-textarea';
  * Internal dependencies
  */
 import './style.scss';
-import PostTitle from 'post-title';
+import PostTitle from '../../post-title';
 
 function TextEditor( { blocks, onChange } ) {
 	return (

editor/modes/visual-editor/block.js

@@ -9,9 +9,9 @@ import { partial } from 'lodash';
 /**
  * Internal dependencies
  */
-import Toolbar from 'components/toolbar';
-import BlockMover from 'components/block-mover';
-import BlockSwitcher from 'components/block-switcher';
+import Toolbar from '../../components/toolbar';
+import BlockMover from '../../components/block-mover';
+import BlockSwitcher from '../../components/block-switcher';
 
 class VisualEditorBlock extends wp.element.Component {
 	constructor() {

editor/modes/visual-editor/index.js

@@ -7,9 +7,9 @@ import { connect } from 'react-redux';
  * Internal dependencies
  */
 import './style.scss';
-import Inserter from 'components/inserter';
+import Inserter from '../../components/inserter';
 import VisualEditorBlock from './block';
-import PostTitle from 'post-title';
+import PostTitle from '../../post-title';
 
 function VisualEditor( { blocks } ) {
 	return (

editor/state.js

@@ -7,7 +7,7 @@ import { keyBy, last, omit, without } from 'lodash';
 /**
  * Internal dependencies
  */
-import { combineUndoableReducers } from 'utils/undoable-reducer';
+import { combineUndoableReducers } from './utils/undoable-reducer';
 
 /**
  * Undoable reducer returning the editor post state, including blocks parsed

package.json

@@ -49,7 +49,6 @@
     "pegjs-loader": "^0.5.1",
     "postcss-loader": "^1.3.3",
     "raw-loader": "^0.5.1",
-    "resolve-entry-modules-webpack-plugin": "^1.0.0",
     "sass-loader": "^6.0.3",
     "sinon": "^2.1.0",
     "sinon-chai": "^2.9.0",

webpack.config.js

@@ -5,7 +5,6 @@
 const glob = require( 'glob' );
 const webpack = require( 'webpack' );
 const ExtractTextPlugin = require( 'extract-text-webpack-plugin' );
-const ResolveEntryModulesPlugin = require( 'resolve-entry-modules-webpack-plugin' );
 
 const config = {
 	entry: {
@@ -26,6 +25,10 @@ const config = {
 		'react-dom/server': 'ReactDOMServer'
 	},
 	resolve: {
+		modules: [
+			__dirname,
+			'node_modules'
+		],
 		alias: {
 			// There are currently resolution errors on RSF's "mitt" dependency
 			// when imported as native ES module
@@ -64,7 +67,6 @@ const config = {
 		]
 	},
 	plugins: [
-		new ResolveEntryModulesPlugin(),
 		new ExtractTextPlugin( {
 			filename: './[name]/build/style.css'
 		} ),