Update READMEs

Author: robertrossmann

README.md

@@ -2,7 +2,7 @@
 
 > Write bulletproof JavaScript like a pro!
 
-**ESLint version required:** `>=1.9.0`
+**ESLint version required:** `>=2.0.0`
 
 ## About
 
@@ -15,79 +15,48 @@ This repository contains various configuration files for the awesome JavaScript
 
 The goal of this project is to help all developers write better code. It should not be a hindrance or cause a major fight about how to write it. Although it will never achieve the "one-config-suits-all" status in terms of coding style, it should achieve that when it comes to writing safe JavaScript.
 
-One or two options for coding style will eventually be provided, preferably after reaching a consensus across the company.
-
 ## Structure
 
 The ESLint rules are semantically grouped into various categories for easy composition.
 
-### [Standard](standard)
-
-These rules are useful to all JavaScript codebases, regardless of platform or developers' coding style preferences. The goal of the Standard rules is to flag unsafe, dangerous or plain-broken JavaScript code. Examples include use of undeclared variables, detecting unreachable code or flagging variables that are no longer used.
-
-> Generally you won't need to use these configuration files directly as they are incorporated into individual environment configurations.
-
 ### [Environments](environments)
 
-These rules are only useful within a specific JavaScript environment, i.e. Node.js. The goal of these rules is to provide a configuration which makes writing code within this environment safer and to configure ESLint specifically for it (i.e. by defining known global variables or enabling certain ES 2015 known to be already implemented).
+These rules are the ones you should be including in your *.eslintrc* configuration. They are separated into categories based on the environment for which the code is being developed. Additionally, each environment provides several levels of "strictness" which the developer can choose from. This level of separation is meant as a means to gradual adoption of **all the rulesets**.
 
-**All environment-specific configuration files should inherit from configurations in [Standard](standard).**
+> It is recommended for new projects to include all levels.
 
 ### [Coding Styles](coding-styles)
 
-These rules help developers adhere to a certain coding style. They do not provide additional safety, but help developers write code in a way that is consistent across the whole codebase, which in long term helps them better maintain that code.
+These rules help developers adhere to a certain coding style. They do not provide code safety, but help developers write code in a way that is consistent across the whole codebase, which in long term helps them better maintain that code.
 
-These rules are intended to be used independently on platform.
+These rules are intended to be used independently on platform. However, you should still consider including rules for your environment if you really care about high-quality JavaScript.
 
 ## Usage
 
-### Initialisation
-
-You will need to put these files into your project somehow. Here are some options:
-
-- Copy/paste these files into a folder within your project (**not recommended**)
-- Add this repository as a git submodule (**preferred**)
-- Add this repository as `npm` dev dependency (see [here](https://docs.npmjs.com/cli/install))
+### Installation
 
-Everyone knows how to copy/paste stuff. Let's look at the second option:
+This package can be installed via npm using Github-URL:
 
-Within your project, do:
+`npm install --save-dev strvcom/js-coding-standards`
 
-`git submodule add https://github.com/strvcom/js-coding-standards.git [destination-dir]`
-
-Where `destination-dir` is an optional folder name of your choice where to put the files (defaults to this project's name).
-
-When you later want to update the ruleset to a newer git revision, `cd` into the submodule's directory and pull, just like any other git repo:
-
-```sh
-# Assuming this is the folder where you decided to put the submodule
-cd js-coding-standards
-git pull
-# Don't forget to commit this "update" in your main project!
-cd ..
-git add js-coding-standards
-git commit
-```
+> Note that the package will be installed as `eslint-config-javascript`, because that's what the package's name is.
 
 ### Configuration
 
-Once you have the rules in place, you must create your own *.eslintrc* configuration file in your project's root and include those configuration files that you want to use for this project. See the [examples](examples) directory for some hints.
-
-> **Note:** Starting from ESLint 1.10, using extensionless *.eslintrc* is **deprecated** - you should always create this file with a supported file extension (`.json`, `.js`, `.yml`, `.yaml`). See ESLint's [release notes for 1.10][eslint-release-1-10] for more information.
+Once the ruleset is installed, you must create your own *.eslintrc* configuration file in your project's root and include those rulesets that you want to use. See the [examples](examples) directory for, well... examples.
 
 ## Status
 
-- **standard:** Feedback required
+- **standard:** Finished
 - **environments**
-  - nodejs: Feedback required
-  - front-end: Not started
-  - Babel: Not started
-- **coding-styles:** WIP
-
-## Feedback
+  - nodejs: Finished
+  - browser: Not started
+  - babel: Not started
+- **coding-styles:** Feedback required
 
-This project is supposed to be a collaborative effort of the whole company, therefore you are invited to provide suggestions and feedback via Github issues & pull requests.
+## License
 
+This software is licensed under the **BSD-3-Clause License**. See the [LICENSE](LICENSE) file for more information.
 
 [eslint-url]: http://eslint.org
 [eslint-release-1-10]: http://eslint.org/blog/2015/11/eslint-v1.10.0-released/#configuration-file-formats

environments/nodejs/README.md

@@ -4,18 +4,20 @@ These configuration files are suitable to lint code which will run on Node.js.
 
 ## Configurations
 
-### latest.yml
+### javascript/environments/nodejs/latest
 
-Suitable for the very latest version of Node.js. It configures ESLint to allow known ES 2015 features as well as includes Node-specific ruleset for known errors.
+Suitable for the very latest version of Node.js. It configures ESLint to allow known ES 2015 features and disallow those still missing as well as includes Node-specific ruleset for known errors.
 
-### legacy.yml
+### javascript/environments/nodejs/legacy
 
 Suitable for legacy versions of Node.js (0.12 and older). Also includes Node-specific rulesets for known errors.
 
-### best-practices.yml
+### javascript/environments/nodejs/best-practices
 
-Use in conjunction with one of the version-specific configuration files. Provides additional safety checks to flag potentially unsafe code.
+Use this ruleset in conjunction with one of the version-specific configuration files. Provides additional safety checks to flag potentially unsafe code.
 
-### optional.yml
+### javascript/environments/nodejs/optional
 
-Use in conjunction with any of the above. Provides additional insights into potential inconsistencies or mistakes in the project.
+Use this ruleset in conjunction with any of the above. Provides additional insights into potential inconsistencies in the project.
+
+> For new projects, it is recommended to enable this ruleset. For existing projects, it is only recommended for the brave.

examples/README.md

@@ -1,29 +1,36 @@
 # Project configuration examples
 
-To use these rulesets, you must have an *.eslintrc* configuration file present in your project root. In this file, you then include those configuration which you would like to use in your project.
-
-> **Note:** Starting from ESLint 1.10, using extensionless *.eslintrc* is **deprecated** - you should always create this file with a supported file extension (`.json`, `.js`, `.yml`, `.yaml`). See ESLint's [release notes for 1.10][eslint-release-1-10] for more information.
-
-The following example uses YAML syntax.
-
-```yaml
----
-# The extends directive allows composition of configuration files
-extends:
-  # Each file adds rule definitions over the previous file, potentially
-  # overwriting some configuration options. Here, we are including the
-  # base configuration for Node.js development and we opt-in to the
-  # best-practices ruleset.
-  - ./js-coding-standards/environments/nodejs/latest.yml
-  - ./js-coding-standards/environments/nodejs/best-practices.yml
-
-# If you need to override some rules specifically for this project,
-# you can do so as usual via the rules property.
-# Per-project rules take precedence over rules defined via included
-# configurations.
-rules:
-  # Enable the valid-jsdoc rule and report violations as hard errors
-  valid-jsdoc: 2
+To use these rulesets, you must have an *.eslintrc* configuration file present in your project root. In this file, you then include those rulesets which you would like to use in your project.
+
+The path to the ruleset must start with `eslint-config-javascript` (this ruleset's package name). Optionally, ESLint allows to drop the `eslint-config` to keep it short. The rest of the path is an actual folder/file in this repository. Extensions can be omitted. For detailed explanation, see ESLint's [shareable configs][shareable-configs].
+
+Your configuration file can either be json, classic Node.js module, or YAML file.
+
+```js
+// .eslintrc.js
+
+module.exports = {
+  // The extends directive allows composition of configuration files
+  extends: [
+    // Each file adds rule definitions over the previous file, potentially
+    // overwriting some configuration options. Here, we are including the
+    // base configuration for Node.js development and we opt-in to the
+    // best-practices ruleset.
+    'javascript/environments/nodejs/latest',
+    'javascript/environments/nodejs/best-practices',
+    // If you are brave enough, you can also extend the "optional" ruleset
+    'javascript/environments/nodejs/optional'
+  ],
+
+  // If you need to override some rules specifically for this project,
+  // you can do so as usual via the rules property.
+  // Per-project rules take precedence over rules defined via included
+  // configurations.
+  rules: {
+    'valid-jsdoc': 2
+  }
+}
 ```
 
-[eslint-release-1-10]: http://eslint.org/blog/2015/11/eslint-v1.10.0-released/#configuration-file-formats
+
+[shareable-configs]: http://eslint.org/docs/developer-guide/shareable-configs.html#using-a-shareable-config