From 070243e4b6cc4e425f2c0674df89903452d1a7cf Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Thu, 8 Feb 2018 00:59:11 -0500
Subject: [PATCH] docs(CONTRIBUTING): update contributing.md (#1973)

---
 CONTRIBUTING.md | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e2714a06..c2882c96 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -45,6 +45,15 @@ To run code linter, use:
 npm run lint
 ```
 
+## API guidelines
+
+When authoring new API methods, consider the following:
+- expose as little information as needed. When in doubt, don’t expose new information
+- methods are used in favor of getters/setters
+  - the only exception is namespaces, e.g. `page.keyboard` and `page.coverage`
+- all string literals must be small case. This includes event names and option values
+- avoid adding "sugar" API (API that is trivially implementable in user-space) unless they're **very** demanded
+
 ## Commit Messages
 
 Commit messages should follow the Semantic Commit Messages format:
@@ -118,9 +127,9 @@ Despite being named 'unit', these are integration tests, making sure public API
 ```
 npm run unit
 ```
-- To filter tests by name:
+- To run tests in parallel, use `-j` flag:
 ```
-npm run unit -- --filter=waitFor
+npm run unit -- -j 4
 ```
 - To run a specific test, substitute the `it` with `fit` (mnemonic rule: '*focus it*'):
 ```js
@@ -154,7 +163,7 @@ HEADLESS=false SLOW_MO=500 npm run unit
 ```
 - To debug a test, "focus" a test first and then run:
 ```
-npm run debug-unit
+node --inspect-brk test/test.js
 ```
 
 ## Public API Coverage