Merge pull request #136 from mobify/release-v2.7.0

jeremywiebe · web-flow · commit d3763aec49ed · 2016-11-24T08:21:44.000-08:00
Release v2.7.0
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 *.sw[a-z]
 .idea/
+node_modules
diff --git a/.remarkrc b/.remarkrc
@@ -0,0 +1,43 @@
+{
+  "presets": ["lint-recommended"],
+  "plugins": {
+    "lint": {
+        "code-block-style": "fenced",
+        "fenced-code-marker": "`",
+        "fenced-code-flag": {
+            "allowEmpty": false
+        },
+        "heading-increment": true,
+        "heading-style": "atx",
+        "link-title-style": "\"",
+        "list-item-bullet-indent": true,
+        "list-item-content-indent": true,
+        "list-item-indent": "space",
+        "maximum-heading-length": 60,
+        "maximum-line-length": 80,
+        "no-consecutive-blank-lines": true,
+        "no-duplicate-headings": true,
+        "no-file-name-articles": true,
+        "no-file-name-articles": true,
+        "no-file-name-consecutive-dashes": true,
+        "no-file-name-consecutive-dashes": true,
+        "no-file-name-irregular-characters": true,
+        "no-file-name-irregular-characters": true,
+        "no-file-name-mixed-case": true,
+        "no-file-name-mixed-case": true,
+        "no-file-name-outer-dashes": true,
+        "no-file-name-outer-dashes": true,
+        "no-heading-content-indent": true,
+        "no-heading-content-indent": true,
+        "no-heading-indent": true,
+        "no-heading-indent": true,
+        "no-multiple-toplevel-headings": 0,
+        "no-table-indentation": true,
+        "no-tabs": true,
+        "no-undefined-references": true,
+        "ordered-list-marker-style": ".",
+        "ordered-list-marker-value": "ordered",
+        "unordered-list-marker-style": "-"
+    }
+  }
+}
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,8 +1,12 @@
-Pending Release
-    -
+2.7.0
+    - Remove `variable-for-property` rule from sass-lint
+    - Adds markdown linting via `lint-md` script
+    - Add ESLint and Atom Text integration how-to doc
+
 2.6.0
     - Remove `variable-for-property` rule from sass-lint [#126](https://github.com/mobify/mobify-code-style/pull/126)
     - Add the eslint jsx-a11y plugin through a new `mobify-es6-react-a11y` configuration [#129](https://github.com/mobify/mobify-code-style/pull/129)
+
 2.5.3
     - Fix #123 by using react/jsx-wrap-multilines rule
     - Migrate CSSComb documentation from Confluence to code style repo
diff --git a/README.md b/README.md
@@ -89,10 +89,18 @@ Make sure to install the following NPM modules:
  - `eslint-import-resolver-webpack`
  - `eslint-plugin-react` (for React/JSX linting only)
 
+## ESLint and Atom
+
+Find out how to integrate [ESLint and Atom Text](./javascript/atom.md).
+
 ## CSS
 Our Client Services team's [CSS Style Guide](/css/Readme.md). Written with a lot of tender care by @kpeatt and @jeffkamo.
 
 ## Python
 
 See the `python` directory of this repo for a standardized `pylintrc` file and
 instructions on using `pep8`, `pylint` and `pyflakes` to check Python code.
+
+## Documentation
+
+See the [`docs`](docs) directory for setup and configuration of Markdown linting.
diff --git a/assets/atom-linter-settings.png b/assets/atom-linter-settings.png
diff --git a/assets/linting-in-atom.gif b/assets/linting-in-atom.gif
diff --git a/bin/lint-md b/bin/lint-md
@@ -0,0 +1,7 @@
+#!/bin/bash -eu
+# Lints Markdown files using Mobify's `.remarkrc` configuration.
+NPM_BIN=$(npm bin)
+REMARK_RC="$NPM_BIN/../mobify-code-style/.remarkrc"
+REMARK_CLI="$NPM_BIN/remark"
+
+$REMARK_CLI --rc-path $REMARK_RC "$@"
diff --git a/css/class-naming-conventions/readme.md b/css/class-naming-conventions/readme.md
diff --git a/docs/README.md b/docs/README.md
@@ -1,3 +1,32 @@
+> Write great documentation! – * [_Mobify Developer Values_](https://github.com/mobify/developer-values#️-write-great-documentation)
+
+At Mobify, documentation is written in markdown.
+
+Documentation should live as close as possible to the code it documents.
+Typically, this means including it in a `docs` folder at the root of the repo.
+Customer facing documentation should be published to a sub path of
+docs.mobify.com.
+
+To make writing document easier, we provide:
+
+* A linter for consistent markdown style.
+* A writing checklist for consistent process.
+
+### Markdown Linting
+
+```bash
+npm install --save-dev mobify-code-style
+
+# 🏃 the linter markdown files in the `docs` folder:
+./node_modules/.bin/lint-md docs
+
+# Arguments are passed to `remark-cli`: https://github.com/wooorm/remark/tree/master/packages/remark-cli
+./node_modules/.bin/lint-md --watch docs
+
+# Try to automajically fix linting warnings:
+./node_modules/.bin/lint-md --output docs
+```
+
 ### Writing Checklist
 
 **Before you start writing**
diff --git a/docs/test/bad.expected.md b/docs/test/bad.expected.md
@@ -0,0 +1,64 @@
+Used to test violations of style.
+
+## BAD: Starting with wrong level heading.
+
+# BAD: Higher level second heading.
+
+### BAD: Skipping levels between headings.
+
+# BAD: Two first level headings.
+
+## BAD: Repeated Headings.
+
+## BAD: Repeated Headings.
+
+BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
+
+BAD: List immedidately following text.
+
+-   list
+
+BAD: One space indents in lists.
+
+-   list
+
+BAD: Two space indents in lists.
+
+-   list
+
+BAD: Non-standard list bullet.
+
+-   Star
+
+BAD: A non-ordered numbered list.
+
+1.  Number
+2.  List
+
+BAD: Fenced code-block with no language.
+
+    # Fenced code block
+
+BAD: Indented code-block.
+
+    # Indented code block
+
+BAD: Missing newline at end of file.
+docs/test/bad.md
+         1:1  warning  Missing newline character at end of file                final-newline                  remark-lint
+    7:1-7:43  warning  Heading levels should increment by one level at a time  heading-increment              remark-lint
+    9:1-9:33  warning  Don’t use multiple top level headings (9:1)             no-multiple-toplevel-headings  remark-lint
+  13:1-13:27  warning  Do not use headings with similar content (11:1)         no-duplicate-headings          remark-lint
+      15:104  warning  Line must be at most 80 characters                      maximum-line-length            remark-lint
+        18:5  warning  Incorrect list-item indent: remove 2 spaces             list-item-indent               remark-lint
+        26:4  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
+   30:1-30:8  warning  Marker style should be `-`                              unordered-list-marker-style    remark-lint
+        30:4  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
+        34:5  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
+   35:1-35:9  warning  Marker should be `2`, was `1`                           ordered-list-marker-value      remark-lint
+        35:5  warning  Incorrect list-item indent: remove 1 space              list-item-indent               remark-lint
+        38:1  warning  Remove 1 line before node                               no-consecutive-blank-lines     remark-lint
+   40:1-42:4  warning  Missing code-language flag                              fenced-code-flag               remark-lint
+  46:1-46:26  warning  Code blocks should be fenced                            code-block-style               remark-lint
+
+⚠ 15 warnings
diff --git a/docs/test/bad.md b/docs/test/bad.md
@@ -0,0 +1,48 @@
+Used to test violations of style.
+
+## BAD: Starting with wrong level heading.
+
+# BAD: Higher level second heading.
+
+### BAD: Skipping levels between headings.
+
+# BAD: Two first level headings.
+
+## BAD: Repeated Headings.
+
+## BAD: Repeated Headings.
+
+BAD: Really, really long lines of text that should probably be wrapped to a more sane length that this.
+
+BAD: List immedidately following text.
+-   list
+
+BAD: One space indents in lists.
+
+- list
+
+BAD: Two space indents in lists.
+
+-  list
+
+BAD: Non-standard list bullet.
+
+*  Star
+
+BAD: A non-ordered numbered list.
+
+1.  Number
+1.  List
+
+
+BAD: Fenced code-block with no language.
+
+```
+# Fenced code block
+```
+
+BAD: Indented code-block.
+
+    # Indented code block
+
+BAD: Missing newline at end of file.
diff --git a/docs/test/good.expected.md b/docs/test/good.expected.md
@@ -0,0 +1,31 @@
+Used to test style.
+
+# GOOD: Starting level one heading.
+
+## GOOD: One level step down headings.
+
+<!--lint disable no-duplicate-headings -->
+
+### GOOD: Repeated Content when rule is disabled
+
+### GOOD: Repeated Content when rule is disabled
+
+<!--lint enable no-duplicate-headings -->
+
+GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
+
+GOOD: Bullet lists with correct bullet.
+
+-   A list!
+
+GOOD: Ordered lists with correct numbers.
+
+1.  Numbered
+2.  Listed
+
+GOOD: Fenced code-blocks with langauge.
+
+```python
+print 'Hello Mobify'
+```
+docs/test/good.md: no issues found
diff --git a/docs/test/good.md b/docs/test/good.md
@@ -0,0 +1,30 @@
+Used to test style.
+
+# GOOD: Starting level one heading.
+
+## GOOD: One level step down headings.
+
+<!--lint disable no-duplicate-headings -->
+
+### GOOD: Repeated Content when rule is disabled
+
+### GOOD: Repeated Content when rule is disabled
+
+<!--lint enable no-duplicate-headings -->
+
+GOOD: Sentences that are just long enough that they don't need to be wrapped!!!
+
+GOOD: Bullet lists with correct bullet.
+
+- A list!
+
+GOOD: Ordered lists with correct numbers.
+
+1. Numbered
+2. Listed
+
+GOOD: Fenced code-blocks with langauge.
+
+```python
+print 'Hello Mobify'
+```
diff --git a/docs/test/test.sh b/docs/test/test.sh
@@ -0,0 +1,17 @@
+#!/bin/bash -eu
+# To test the remark configuration, we use two test fixtures files:
+# `good.md` and `bad.md`
+#
+# The result of running our remark configuration on them is commited as
+# `.expected` files. If we change our configuration, a new output will be
+# expected and these files must be re-generated.
+NPM_BIN=$(npm bin)
+TEST_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+
+# Re-generate `.expected` files with current configuration.
+# "$NPM_BIN/remark" "$TEST_DIR/good.md" --no-color > "$TEST_DIR/good.expected.md" 2>&1
+# "$NPM_BIN/remark" "$TEST_DIR/bad.md" --no-color > "$TEST_DIR/bad.expected.md" 2>&1
+
+# Compare remark output with expected output. Fail on diff.
+diff <("$NPM_BIN/remark" "$TEST_DIR/good.md" --no-color 2>&1) "$TEST_DIR/good.expected.md"
+diff <("$NPM_BIN/remark" "$TEST_DIR/bad.md" --no-color 2>&1) "$TEST_DIR/bad.expected.md"
diff --git a/es5/README.md b/es5/README.md
@@ -4,6 +4,10 @@ This folder includes a default ESLint configuration, `mobify-es5.yml`, compatibl
 
 # General
 
+## ESLint and Atom
+
+Find out how to integrate [ESLint and Atom Text](../javascript/atom.md).
+
 ##Comments
 
 Please comment code extensively. More comments are always better than fewer comments. Comments should describe the why of your code - not what the code is doing:
diff --git a/es6/README.md b/es6/README.md
@@ -14,6 +14,14 @@ JSX accessibility linting is available with the `mobify-es6-react-a11y.yml` conf
 - `eslint-plugin-react`
 - `eslint-plugin-jsx-a11y`
 
+## ESLint and Atom
+
+Find out how to integrate [ESLint and Atom Text](../javascript/atom.md).
+
+*NOTE*: While these instructions use the code style's ES5 config file, an ES6 file may be alternatively
+substituted. Mobify's ES6-compatible projects will have their own `.eslintrc.yml` config file, which
+will be enforced by Atom and `linter-eslint`.
+
 ## Global Names and Environments
 
 By default, the lint configuration only assumes the standard set of
diff --git a/javascript/README.md b/javascript/README.md
@@ -6,6 +6,11 @@ with ESLint 1.x or lower.**
 **For new projects or ESLint 2.x and up, use the contents of the `mobify-code-style/es5` directory**
 
 # General
+
+## ESLint and Atom
+
+Find out how to integrate [ESLint and Atom Text](./atom.md).
+
 ##Comments
 
 Please comment code extensively. More comments are always better than fewer comments. Comments should describe the why of your code - not what the code is doing:
diff --git a/javascript/atom.md b/javascript/atom.md
@@ -0,0 +1,34 @@
+# ESLint and Atom Text
+
+![Linting in Atom](../assets/linting-in-atom.gif "Linting in Atom")
+
+Instead of relying on your project's linting tasks (`grunt lint` or `npm run lint`), wouldn't it be better to have Atom proactively linting your JS as you compose it, using Mobify's code style as a ruleset? Here's how!
+
+## Prerequisites
+
+1. Install Node.js and NPM with [NVM](https://github.com/creationix/nvm)
+1. Install eslint and Mobify's code style globally:
+```bash
+npm install -g eslint
+npm install -g mobify-code-style
+```
+
+## Instructions for Atom
+
+1. Install the [linter package](https://atom.io/packages/linter)
+1. Install the [linter-eslint package](https://atom.io/packages/linter-eslint)
+1. Open your Atom package settings for `linter-eslint` and ensure:
+    * Your `ESLint Path` is set
+        * Find your ESLint path by running `which eslint` in a terminal
+    * Your `.eslintrc Path` is set to the ES5 config file from Mobify's code style
+        * This config is the fallback for when an existing ESLint config does not exist in the current project
+    * Your `Global Node Installation Path` is set
+        * Find this by running `npm get prefix` in a terminal
+
+Your Atom settings will look something like this:
+![Atom Linter Settings](../assets/atom-linter-settings.png "Atom Linter Settings")
+
+Now restart Atom and open a JS file to see it in action.
+
+*Tip*: When working on a project that does not need to conform to this code style,
+toggle the linter off/on by opening the command palette with <kbd>shift</kbd>+<kbd>⌘</kbd>+<kbd>p</kbd> (Mac) or <kbd>shift</kbd>+<kbd>ctrl</kbd>+<kbd>p</kbd> (PC) and type + select `Linter: Toggle`
diff --git a/package.json b/package.json

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`*.sw[a-z]`
`2`	`2`	`.idea/`
	`3`	`+node_modules`