Merge pull request #3951 from maciej-ka/improve-contributing-docs

docs: improve how to contribute

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Install this package's dependencies with `npm`:
 npm install
 ```
 
-## Development
+## Build
 
 Run the following to build this library and watch its source files for changes:
 
@@ -20,6 +20,107 @@ npm run dev
 
 You will now have a fully functioning local build of this library ready to be used. **Leave the `start` script running**, and continue with a new Terminal/shell window.
 
+## Work on a fix or feature
+
+To work on a fix or feature and to preview changes in source code, use samples included, or start a new project with modified Apexcharts as a dependency.
+
+### View included samples
+
+There are many samples included which can be used as a quick start when working on contributions. Start an HTTP server to view them.
+
+```bash
+cd apexcharts.js
+npx browser-sync start --server --files "." --directory --startPath "/samples"
+```
+
+And start working on a feature or fix. Changes in source code should be immediately visible in the browser due to automatic reload on changes.
+
+### Start a dependent new project
+
+Mark the Apexcharts folder under modifications so that npm can use it in new projects. This step is needed only once ever.
+
+```bash
+cd apexcharts.js
+npm link
+```
+
+Start a build with a slightly different command than mentioned before and leave the terminal running.
+
+```bash
+npm run dev:cjs
+```
+
+In a new terminal window, create a new project outside of the Apexcharts folder.
+
+```bash
+ mkdir ~/new-project && cd ~/new-project &&
+npm init -y
+```
+
+Add the previously marked Apexchart folder under modification as a npm dependency to the new project. This step has to be repeated after every `npm i` run in the new project.
+
+```bash
+npm link apexcharts
+```
+
+Write a basic Apexchart use scenario.
+
+index.html
+
+```html
+<div id="chart"></div>
+<script type="module" src="./main.js"></script>
+```
+
+main.js
+
+```js
+import ApexCharts from 'apexcharts'
+
+const options = {
+  chart: { type: 'line' },
+  series: [
+    {
+      name: 'sales',
+      data: [30, 40, 45, 50, 49, 60, 70, 91, 125],
+    },
+  ],
+  xaxis: { categories: [1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999] },
+}
+const chart = new ApexCharts(document.querySelector('#chart'), options)
+chart.render()
+```
+
+Finally, run bundler and HTTP server, which will auto-reload on changes in the new project and Apexcharts source code. Leave the terminal open with this command.
+
+```bash
+npx parcel serve index.html
+```
+
+And visit http://localhost:1234
+
+## Tests
+
+Apexcharts comes with unit tests and integration tests. Integration tests are based on viewing sample projects in a test browser, taking screenshots, and comparing them with previously captured screenshots to detect differences. To run them all, use:
+
+```bash
+npm run test
+```
+
+If this command ends with an error `Error: Unable to launch browser, error message: Chromium revision is not downloaded.` then calling puppeteer install may solve the problem:
+
+```bash
+node node_modules/puppeteer/install.js
+```
+
+E2e tests will likely fail due to minor differences in OS and the browser version used to take screenshots. To address this, before working on a feature, recapture screenshots using this command:
+
+```bash
+npm run e2e:update
+```
+
+This way, when later working on a feature or fix, `npm run test` command will detect only screenshots affected by changes done. Please avoid sending locally generated screenshots in PR, by excluding `tests/e2e/snapshots` folder from commit.
+
 ## Send your changes back to us! :revolving_hearts:
 
 We'd love for you to contribute your changes back to `apexcharts.js`! To do that, it would be great if you could commit your changes to a separate feature branch and open a Pull Request for those changes.
@@ -37,11 +138,3 @@ git push --set-upstream origin feature/branch-name-here
 ```
 
 After these steps, you should be able to create a new Pull Request for this repository. If you hit any issues following these instructions, please open an issue and we'll see if we can improve these instructions even further.
-
-## Add tests for your changes
-
-As of now, we have very less tests, and from now on, would like to pay extra attention to it. It would be great if the changes you did could be tested somehow. Our tests live inside the `tests` directory, and they can be run with the following command:
-
-```sh
-npm run test
-```

README.md

@@ -154,12 +154,12 @@ Utilize sparklines to indicate trends in data, for example, occasional increment
 <p align="center"><a href="https://apexcharts.com/javascript-chart-demos/sparklines/"><img src="https://apexcharts.com/media/sparklines.png" alt="sparkline-chart" /></a></p>
 
 
-## Need Advanced Data Grid for your next project? 
-We partnered with Infragistics, creators of the fastest data grids on the planet! Ignite UI Grids can handle unlimited rows and columns of data while providing access to custom templates and real-time data updates. 
+## Need Advanced Data Grid for your next project?
+We partnered with Infragistics, creators of the fastest data grids on the planet! Ignite UI Grids can handle unlimited rows and columns of data while providing access to custom templates and real-time data updates.
 
 <p align="center"><a href="https://www.infragistics.com/products/ignite-ui-angular/angular/components/grid/grid" target="_blank"><img src="https://apexcharts.com/media/infragistics-data-grid.png" /></a></p>
 
-Featuring an intuitive API for easy theming and branding, you can quickly bind to data with minimal hand-on coding. The grid is available in most of your favorite frameworks:  
+Featuring an intuitive API for easy theming and branding, you can quickly bind to data with minimal hand-on coding. The grid is available in most of your favorite frameworks:
 
 <a target="_blank" href="https://www.infragistics.com/products/ignite-ui-angular/angular/components/grid/grid">Angular Data Grid</a> | <a target="_blank" href="https://www.infragistics.com/products/ignite-ui-react/react/components/grids">React Data Grid</a> | <a target="_blank" href="https://www.infragistics.com/products/ignite-ui-blazor/blazor/components/data-grid">Blazor Data Grid</a> | <a target="_blank" href="https://www.infragistics.com/products/ignite-ui-web-components/web-components/components/data-grid">Web Components DataGrid</a> | <a target="_blank" href="https://www.igniteui.com/grid/overview">jQuery Data Grid </a>
 
@@ -201,6 +201,8 @@ npm run dev
 
 This will start the webpack watch and any changes you make to `src` folder will auto-compile and output will be produced in the `dist` folder.
 
+More details in [Contributing Guidelines](CONTRIBUTING.md).
+
 #### Minifying the src
 
 ```bash