Merge pull request #5386 from open-sausages/pulls/4.0/js-conventions

Documented JS coding conventions

docs/en/00_Getting_Started/04_Directory_Structure.md

@@ -26,7 +26,11 @@ existing modules or the directories lists in "Core Structure".
  | `<mysite>/templates`  | HTML [templates](/developer_guides/templates) with *.ss-extension                     |
  | `<mysite>/css `       | CSS files                                                           |
  | `<mysite>/images `    | Images used in the HTML templates                                   |
- | `<mysite>/javascript` | Javascript and other script files 
+ | `<mysite>/javascript` | Javascript and other script files |
+ | `<mysite>/client`     | More complex projects can alternatively contain frontend assets in a common `client` folder |
+
+Check our [JavaScript Coding Conventions](javascript_coding_conventions) for more details
+on folder and file naming in SilverStripe core modules.
 
 ## Themes Structure
 

docs/en/00_Getting_Started/05_Coding_Conventions.md

@@ -1,8 +1,8 @@
-# Coding Conventions
+# PHP Coding Conventions
 
 This document provides guidelines for code formatting and documentation
 to developers contributing to SilverStripe. It applies to all PHP files
-in the framework/ and cms/ modules, as well as any supported additional modules.
+in the `framework/` and `cms/` modules, as well as any supported additional modules.
 
 Coding standards are an important aspect for every software project,
 and facilitate collaboration by making code more consistent and readable.
@@ -458,4 +458,5 @@ which are licensed under BSD (see [license](http://framework.zend.com/license)).
 
 ## Related
 
+ * [JavaScript Coding Conventions](/getting_started/javascript_coding_conventions)
  * [Reference: CMS Architecture](/developer_guides/customising_the_admin_interface/cms_architecture)

docs/en/00_Getting_Started/06_JavaScript_Coding_Conventions.md

@@ -0,0 +1,41 @@
+# JavaScript Coding Conventions
+
+## Overview
+
+This document provides guidelines for code formatting to developers contributing
+to SilverStripe. It applies to all JavaScript files in the `framework/` and `cms/` modules.
+
+In 2016, SilverStripe started a rewrite of its CMS interface in
+[ES6](https://en.wikipedia.org/wiki/ECMAScript) and
+[ReactJS](http://facebook.github.io/react/). Code written prior to this rewrite
+might not follow these conventions, and is placed in a `legacy/` folder structure.
+
+## Conventions
+
+We follow the [AirBnB JavaScript Conventions](https://github.com/airbnb/javascript).
+A lot of their rules can be validated via [ESLint](http://eslint.org/),
+and can be checked locally via `npm run lint`.
+
+## File and Folder Naming
+
+- All frontend files (CSS, JavaScript, images) should be placed in
+  a `client/` folder on the top level of the module
+- Frontend files relating to the `framework` CMS UI should be placed in `admin/client`
+- File names should follow the [AirBnB Naming Conventions](https://github.com/airbnb/javascript#naming-conventions)
+- The `client/src/components` folder should contain only React
+  [presentational components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0#.r635clean).
+  These components should be self-contained, and shouldn't know about Redux state.
+- The `client/src/containers` folder should contain only React
+  [container components](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0#.r635clean)
+- React classes in `client/src/components` and `client/src/containers` should
+  have one folder per component, alongside a `README.md` and SCSS files where applicable.
+- The `client/src/state` folder should contain [Redux](http://redux.js.org/)
+  actions, action types and reducers. Each set of these should be kept in a folder
+  named the same as its [reducer state key](http://redux.js.org/docs/basics/Reducers.html).
+- JavaScript tests should be named after the module/class they're testing,
+  with their file name suffixed with `-tests.js`.
+- JavaScript tests should be placed in a `tests/` subfolder alongside the module code.
+
+## Related
+
+* [PHP Coding Conventions](/getting_started/coding_conventions)