[incubator-echarts.wiki] branch master updated: Created How to debug? (markdown)

[ov...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ovilia pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-echarts.wiki.git


The following commit(s) were added to refs/heads/master by this push:
     new 0ddcad1  Created How to debug? (markdown)
0ddcad1 is described below

commit 0ddcad10809d8410102f3dacae47773ccdc695c0
Author: Ovilia <zw...@gmail.com>
AuthorDate: Mon Dec 16 11:39:01 2019 +0800

    Created How to debug? (markdown)
---
 How-to-debug?.md | 133 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/How-to-debug?.md b/How-to-debug?.md
new file mode 100644
index 0000000..ff16f52
--- /dev/null
+++ b/How-to-debug?.md
@@ -0,0 +1,133 @@
+The following steps help you to set up a developing environment for ECharts.
+
+### 1. Clone the ECharts project
+
+If you wish to make pull requests, you should **fork the ECharts project** first. Otherwise, just clone it locally.
+
+```bash
+git clone git@github.com:apache/incubator-echarts.git
+```
+
+[ZRender](https://github.com/ecomfe/zrender) is the rendering library under the hood. You need to clone it along with ECharts.
+
+```bash
+git clone git@github.com:ecomfe/zrender.git
+```
+
+We assume these projects are downloaded at `~/workspace/echarts` and `~/workspace/zrender` in the following steps. But their locations can be arbitrary.
+
+
+### 2. Install dependencies
+
+```bash
+cd ~/workspace/echarts
+npm install
+cd ~/workspace/zrender
+npm install
+```
+
+Sometimes, in order to fix an issue within echarts, changes have to be made inside the codebase of zrender. So we need to link zrender to `echarts/node_modules/zrender'.
+
+```bash
+cd ~/workspace/echarts
+rm node_modules/zrender 
+ln -s ~/workspace/zrender node_modules/zrender
+```
+
+You should replace the above path with the path in your environment. Use an absolute path of zrender for the `ln` instruction. 
+
+After that, running `ls node_modules/zrender` to test if the content of the directory can be printed. If not, you probably have made a mistake with the link.
+
+> Using `npm link` cannot watch the changes in zrender. So please follow the above instructions.
+
+Now, running `node build/build.js` watches changes both in echarts and zrender source directory.
+
+### 3. Run and debug
+
+To build the ECharts project and watch source file changes (including ZRender project) to rebuild:
+
+```bash
+cd ~/workspace/echarts
+node build/build.js --watch
+```
+
+To build once:
+
+```bash
+node build/build.js
+```
+
+Then, open the test cases under `~/workspace/echarts/test` in Web browser. You can add breakpoints under `src` directory. For example, in Chrome Inspect, it looks like:
+
+![Chrome inspect](https://github.com/apache/incubator-echarts/raw/master/asset/contributing-inspect.png)
+
+
+### 4. Add test cases
+
+In most cases, one or more test cases should be added when developing a feature or fixing a bug.
+All of the existing test cases are in directory `~/workspace/echarts/test`.
+Check the file `~/workspace/echarts/test/dataZoom-action.html` as an example.
+
+**Organize test cases:**
+Each file can be regard as a **test suite** and each chart in the file can be regard as a **test case**,
+which contains one or multiple expected results (check points).
+If a feature or bug is related to a chart type or a component type, probably it should belongs to
+a test file named `chartOrComponentType-someSubCategory.html`. Or some common feature is related
+to multiple chart or component or has nothing to do with chart and component, probably it should
+belongs a test file named `featureName-someSubCateogory.html`.
+
+**The naming of a test file:**
+Generally speaking, the name of the test file should start with a chart type or component type
+or a common feature name (like "hoverStyle", "clip").
+
+**Add a test case:**
+If intending to add a test case, firstly try to find in the existing test files which file this
+new test case might belongs to.
+If an existing file found, add the test case to the file.
+Otherwise, add a new test file by commands as follows:
+
+```shell
+# Make a file named "bar-action.html" in directory "echarts/test" with 1 initial chart.
+npm run mktest bar-action
+# or `npm run mktest bar-action.html`
+
+# Make a file named "bar-action.html" in directory "echarts/test" with 5 initial charts.
+npm run mktest bar-action 5
+```
+
+**The expected results and the instructions of user interaction:**
+Although we have auto-visual-test tool to run tests, we should better write the expected result
+(check points) for each test cases for manual checking.
+Some cases need user interactions involved. The instructions should be written clearly.
+The expected results and the user instructions should be written in the `title` filed when
+creating a test by `testHelper.create` as follows:
+
+```js
+var chart = testHelper.create(echarts, 'main0', {
+    title: [
+        'Hover on the red circle',
+        '**A blue label** should appear on the **top of red circle**.'
+    ],
+    option: option
+});
+```
+
+
+### 5. Run test cases
+
+Before making a pull request, you must run `npm run test` locally to do the unit tests.
+
+Visual tests are optional. If you changed view related logic, please test the related visual cases. For example, if you add a new layout for pie chart labels, you should run the visual tests of all pie test cases and add new cases if needed.
+
+```bash
+# puppeteer is not in the devDependencies and needs to be installed manually
+npm install puppeteer --no-save
+npm run test:visual
+```
+
+It will run all the test cases under `~/workspace/echarts/test` automatically to compare with the previous version. You can use this to check if your code bring some breaking change.
+
+### Next Steps
+
+Please checkout [How to make a pull request?](https://github.com/apache/incubator-echarts/wiki/How-to-make-a-pull-request-to-the-ECharts-project%3F).
+


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org