doc: reorganize readme (#1441)

Author: legendecas

CONTRIBUTING.md

@@ -1,40 +1,147 @@
+# Contributing to **node-addon-api**
 
-# Developer's Certificate of Origin 1.1
+* [Code of Conduct](#code-of-conduct)
+* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin)
+* [Tests](#tests)
+* [Debug](#debug)
+* [Benchmarks](#benchmarks)
+* [node-addon-api Contribution Philosophy](#node-addon-api-contribution-philosophy)
 
+## Code of Conduct
+
+The Node.js project has a
+[Code of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md)
+to which all contributors must adhere.
+
+See [details on our policy on Code of Conduct](https://github.com/nodejs/node/blob/main/doc/contributing/code-of-conduct.md).
+
+<a id="developers-certificate-of-origin"></a>
+
+## Developer's Certificate of Origin 1.1
+
+<pre>
 By making a contribution to this project, I certify that:
 
  (a) The contribution was created in whole or in part by me and I
-     have the right to submit it under the open-source license
+     have the right to submit it under the open source license
      indicated in the file; or
 
  (b) The contribution is based upon previous work that, to the best
      of my knowledge, is covered under an appropriate open source
      license and I have the right under that license to submit that
      work with modifications, whether created in whole or in part
-     by me, under the same open-source license (unless I am
+     by me, under the same open source license (unless I am
      permitted to submit under a different license), as indicated
      in the file; or
 
  (c) The contribution was provided directly to me by some other
-     person who certified (a), (b), or (c) and I have not modified
+     person who certified (a), (b) or (c) and I have not modified
      it.
 
  (d) I understand and agree that this project and the contribution
      are public and that a record of the contribution (including all
      personal information I submit with it, including my sign-off) is
      maintained indefinitely and may be redistributed consistent with
      this project or the open source license(s) involved.
+</pre>
+
+
+## Tests
+
+To run the **node-addon-api** tests do:
+
+```
+npm install
+npm test
+```
+
+To avoid testing the deprecated portions of the API run
+```
+npm install
+npm test --disable-deprecated
+```
+
+To run the tests targeting a specific version of Node-API run
+```
+npm install
+export NAPI_VERSION=X
+npm test --NAPI_VERSION=X
+```
+
+where X is the version of Node-API you want to target.
+
+To run a specific unit test, filter conditions are available
+
+**Example:**
+  compile and run only tests on objectwrap.cc and objectwrap.js
+  ```
+    npm run unit --filter=objectwrap
+  ```
+
+Multiple unit tests cane be selected with wildcards
+
+**Example:**
+compile and run all test files ending with "reference" -> function_reference.cc, object_reference.cc, reference.cc
+ ```
+    npm run unit --filter=*reference
+ ```
+
+Multiple filter conditions can be joined to broaden the test selection
 
-# **node-addon-api** Contribution Philosophy
+**Example:**
+ compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file
+    npm run unit --filter='*function objectwrap'
+
+## Debug
+
+To run the **node-addon-api** tests with `--debug` option:
+
+```
+npm run-script dev
+```
+
+If you want a faster build, you might use the following option:
+
+```
+npm run-script dev:incremental
+```
+
+Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/HEAD/test)**
+
+## Benchmarks
+
+You can run the available benchmarks using the following command:
+
+```
+npm run-script benchmark
+```
+
+See [benchmark/README.md](benchmark/README.md) for more details about running and adding benchmarks.
+
+## **node-addon-api** Contribution Philosophy
 
 The **node-addon-api** team loves contributions. There are many ways in which you can
 contribute to **node-addon-api**:
-- Source code fixes
+- [New APIs](#new-apis)
+- [Source code fixes](#source-changes)
 - Additional tests
 - Documentation improvements
 - Joining the Node-API working group and participating in meetings
 
-## Source changes
+### New APIs
+
+As new APIs are added to Node-API, node-addon-api must be updated to provide
+wrappers for those new APIs. For this reason, node-addon-api provides
+methods that allow callers to obtain the underlying Node-API handles so
+direct calls to Node-API and the use of the objects/methods provided by
+node-addon-api can be used together. For example, in order to be able
+to use an API for which the node-addon-api does not yet provide a wrapper.
+
+APIs exposed by node-addon-api are generally used to create and
+manipulate JavaScript values. Concepts and operations generally map
+to ideas specified in the **ECMA262 Language Specification**.
+
+### Source changes
 
 **node-addon-api** is meant to be a thin convenience wrapper around Node-API. With this
 in mind, contributions of any new APIs that wrap around a core Node-API API will
@@ -56,6 +163,7 @@ idioms while writing native addons with **node-addon-api**.
 where folks can build on top of it.
 
 #### Larger Core
+
 This is probably our simplest option in terms of immediate action needed. It
 would involve landing any open PRs against **node-addon-api**, and continuing to
 encourage folks to make PRs for utility helpers against the same repository.
@@ -65,6 +173,7 @@ The downside of the approach is the following:
 - More maintenance burden on the Node-API WG core team.
 
 #### Extras Package
+
 This involves us spinning up a new package that contains the utility classes
 and methods. This has the benefit of having a separate module where helpers
 make it easier to implement certain patterns and idioms for native addons
@@ -78,6 +187,7 @@ belongs in **node-addon-api** vs **node-addon-api-extras**)
 - Unclear if the maintenance burden on the Node-API WG is reduced or not
 
 #### Ecosystem
+
 This doesn't require a ton of up-front work from the Node-API WG. Instead of
 accepting utility PRs into **node-addon-api** or creating and maintaining a new
 module, the WG will encourage the creation of an ecosystem of modules that