notes about yml support and debugging

Author: krzkaczor

README.md

@@ -30,12 +30,13 @@ Expect more docs soon...
 
 1. [Getting started](getting-started.md)
 1. [How does it work?](how-does-it-work.md)
-1. [Configuration — codechecks.json/ts/js](configuration.md)
+1. [Configuration — codechecks.yml/json/ts/js](configuration.md)
 1. [Checks (plugins) development](developing-checks.md)
    1. Developing reusable checks
    1. Testing checks
 1. [How to build X?](how-to-build-X.md)
 1. [Client API reference](client-api.md)
 1. [Localmode](localmode.md)
+1. [Debugging](debugging.md)
 1. [FAQ](faq.md)
 1. [Roadmap](roadmap.md)

client-api.md

@@ -16,7 +16,7 @@ export class Client {
   report(report: CodeChecksReport): Promise<void>;
   success(report: CodeChecksReportBody): Promise<void>;
   failure(report: CodeChecksReportBody): Promise<void>;
-  
+
   isPr(): boolean;
 
   getArtifactLink(path: string): string;

configuration.md

@@ -1,7 +1,30 @@
 # Configuration
 
-JS Client by default will try to find codechecks.json, codechecks.js and codechecks.ts files and
-execute all that exist. In near future we might support yml as well.
+Client by default will try to find `codechecks.yml`, `codechecks.json`, `codechecks.js` and
+`codechecks.ts` files and execute all that exist.
+
+To specify custom file just use `codechecks [FILES]`. Specifying multiple files can be useful
+because you should favour declarative configs (yml/json) but sometimes you still have custom rules
+that you need to define in `js` or `ts` files.
+
+## codechecks.yml
+
+<!-- prettier-ignore -->
+```yml
+checks:
+- name: build-size-watcher
+  options:
+    gzip: false
+    files:
+    - path: "./dist/**/*.d.ts"
+    - path: "./dist/**/*.js"
+```
+
+This is a preferable way of defining checks (plugins). It's fully declarative and using yml make it
+very readable. It works only with external checks ie. checks that part of your package.json.
+
+Resolution engine for check's names will first try to find: `@codechecks/NAME` and then NAME in node
+modules and pass options.
 
 ## codechecks.json
 
@@ -21,15 +44,10 @@ execute all that exist. In near future we might support yml as well.
 }
 ```
 
-This is a preferable way of executing external checks (plugins). It's fully declarative. It will
-first try to find: `@codechecks/NAME` and then NAME in node modules and pass options.
+It's the same as YML config but written in JSON.
 
 ## codechecks.ts/js
 
 If you want to execute arbitrary logic this is the way to go. The only thing you need to do is
 export async function from your module. We support es6 named export `main`, default export and
 commonjs export.
-
-To specify custom file just use codechecks [FILES] Specifying multiple files makes sense because you
-should favour JSON configs but sometimes you still have custom rules that you need to define in `js`
-or `ts`.

debugging.md

@@ -0,0 +1,7 @@
+# Debugging
+
+We use `debug` package to provide verbose logs. Run codechecks CLI using:
+
+```sh
+DEBUG=codechecks:* codechecks
+```

developing-checks.md

@@ -113,3 +113,8 @@ this project are part of `/example` dir.
 
 You can find more complicated example here:
 https://github.com/codechecks/build-size-watcher/tree/master/src/__tests__
+
+## Debugging
+
+For compatibility with codechecks client, to provide debug logs use `debug` package with
+`codechecks:YOUR_CHECK_NAME` namespace.