From e32f69819ec39ad8cb230e2ccea24b96b5fe68f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Sajn=C3=B3g?= <msajnog93@gmail.com>
Date: Sat, 21 Jul 2018 21:58:24 +0200
Subject: [PATCH] Add "working-with-rules" section in README

---
 README.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/README.md b/README.md
index b070b4098..fe9cad2d4 100644
--- a/README.md
+++ b/README.md
@@ -288,6 +288,30 @@ In order to add a new rule, you should:
 
 We're more than happy to see potential contributions, so don't hesitate. If you have any suggestions, ideas or problems feel free to add new [issue](https://github.com/vuejs/eslint-plugin-vue/issues), but first please make sure your question does not repeat previous ones.
 
+### Working with rules
+
+Before you start writing new rule, please read the [official ESLint guide](https://eslint.org/docs/developer-guide/working-with-rules).
+
+Next in order to get an idea how does the AST of the code that you want to check looks like, you can use one of the following applications:
+- [astexplorer.net](http://astexplorer.net/) - best tool to inspect ASTs, but it doesn't support Vue templates yet
+- [ast.js.org](https://ast.js.org/) - not fully featured, but supports Vue templates syntax
+
+Since single file components in Vue are not plain JavaScript, we can't use the default parser, and we had to introduce additional one: `vue-eslint-parser`, that generates enhanced AST with nodes that represent specific parts of the template syntax, as well as what's inside the `<script>` tag.
+
+To know more about certain nodes in produced ASTs, go here:
+- [ESTree docs](https://github.com/estree/estree)
+- [vue-eslint-parser AST docs](https://github.com/mysticatea/vue-eslint-parser/blob/master/docs/ast.md)
+
+The `vue-eslint-parser` provides few useful parser services, to help traverse the produced AST and access tokens of the template:
+- `context.parserServices.defineTemplateBodyVisitor(visitor, scriptVisitor)`
+- `context.parserServices.getTemplateBodyTokenStore()`
+
+Check out an [example rule](https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/rules/mustache-interpolation-spacing.js) to get a better understanding of how these work.
+
+Please be aware that regarding what kind of code examples you'll write in tests, you'll have to accordingly setup the parser in `RuleTester` (you can do it on per test case basis though). [See an example here](https://github.com/vuejs/eslint-plugin-vue/blob/master/tests/lib/rules/attribute-hyphenation.js#L19)
+
+If you'll stuck, remember there are plenty of rules you can learn from already, and if you can't find the right solution - don't hesitate to reach out in issues. We're happy to help!
+
 ## :lock: License
 
 See the [LICENSE](LICENSE) file for license rights and limitations (MIT).