From c13c947448b7114cf6ef11090ab4b060b9f0d9fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Boisseau-Sierra?= Date: Wed, 27 Apr 2022 15:58:16 +0100 Subject: [PATCH 1/3] chore: Beautify CONTRIBUTING MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Automatically done using the Markdown-All-In-One extension for VSCode: https://open-vsx.org/extension/yzhang/markdown-all-in-one Signed-off-by: Étienne Boisseau-Sierra --- CONTRIBUTING.md | 47 +++++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 738f018873433..e8e6e3c6b6f0a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,6 +55,7 @@ little bit helps, and credit will always be given. - [Images](#images) - [Flask server](#flask-server) - [OS Dependencies](#os-dependencies) + - [Dependencies](#dependencies) - [Logging to the browser console](#logging-to-the-browser-console) - [Frontend](#frontend) - [Prerequisite](#prerequisite) @@ -68,11 +69,13 @@ little bit helps, and credit will always be given. - [Feature flags](#feature-flags) - [Git Hooks](#git-hooks) - [Linting](#linting) + - [Python](#python) + - [TypeScript](#typescript) - [Conventions](#conventions) - - [Python](#python-conventions) + - [Python Conventions](#python-conventions) - [Typing](#typing) - - [Python](#python-typing) - - [TypeScript](#typeScript-typing) + - [Python Typing](#python-typing) + - [TypeScript Typing](#typescript-typing) - [Testing](#testing) - [Python Testing](#python-testing) - [Frontend Testing](#frontend-testing) @@ -92,7 +95,7 @@ little bit helps, and credit will always be given. - [SQL Lab Async](#sql-lab-async) - [Async Chart Queries](#async-chart-queries) - [Chart Parameters](#chart-parameters) - - [Datasource & Chart Type](#datasource--chart-type) + - [Datasource \& Chart Type](#datasource--chart-type) - [Time](#time) - [GROUP BY](#group-by) - [NOT GROUPED BY](#not-grouped-by) @@ -1314,14 +1317,14 @@ Note not all fields are correctly categorized. The fields vary based on visualiz ### Datasource & Chart Type -| Field | Type | Notes | -| ----------------- | -------- | ----------------------------------- | -| `database_name` | _string_ | _Deprecated?_ | +| Field | Type | Notes | +| ----------------- | -------- | ------------------------------------ | +| `database_name` | _string_ | _Deprecated?_ | | `datasource` | _string_ | `__` | -| `datasource_id` | _string_ | _Deprecated?_ See `datasource` | -| `datasource_name` | _string_ | _Deprecated?_ | -| `datasource_type` | _string_ | _Deprecated?_ See `datasource` | -| `viz_type` | _string_ | The **Visualization Type** widget | +| `datasource_id` | _string_ | _Deprecated?_ See `datasource` | +| `datasource_name` | _string_ | _Deprecated?_ | +| `datasource_type` | _string_ | _Deprecated?_ See `datasource` | +| `viz_type` | _string_ | The **Visualization Type** widget | ### Time @@ -1364,17 +1367,17 @@ Note not all fields are correctly categorized. The fields vary based on visualiz ### Query -| Field | Type | Notes | -| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | ------------------------------------------------- | -| `adhoc_filters` | _array(object)_ | The **Filters** widget | -| `extra_filters` | _array(object)_ | Another pathway to the **Filters** widget.
It is generally used to pass dashboard filter parameters to a chart.
It can be used for appending additional filters to a chart that has been saved with its own filters on an ad-hoc basis if the chart is being used as a standalone widget.

For implementation examples see : [utils test.py](https://github.com/apache/superset/blob/66a4c94a1ed542e69fe6399bab4c01d4540486cf/tests/utils_tests.py#L181)
For insight into how superset processes the contents of this parameter see: [exploreUtils/index.js](https://github.com/apache/superset/blob/93c7f5bb446ec6895d7702835f3157426955d5a9/superset-frontend/src/explore/exploreUtils/index.js#L159) | -| `columns` | _array(string)_ | The **Breakdowns** widget | -| `groupby` | _array(string)_ | The **Group by** or **Series** widget | -| `limit` | _number_ | The **Series Limit** widget | -| `metric`
`metric_2`
`metrics`
`percent_metrics`
`secondary_metric`
`size`
`x`
`y` | _string_,_object_,_array(string)_,_array(object)_ | The metric(s) depending on the visualization type | -| `order_asc` | _boolean_ | The **Sort Descending** widget | -| `row_limit` | _number_ | The **Row limit** widget | -| `timeseries_limit_metric` | _object_ | The **Sort By** widget | +| Field | Type | Notes | +| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `adhoc_filters` | _array(object)_ | The **Filters** widget | +| `extra_filters` | _array(object)_ | Another pathway to the **Filters** widget.
It is generally used to pass dashboard filter parameters to a chart.
It can be used for appending additional filters to a chart that has been saved with its own filters on an ad-hoc basis if the chart is being used as a standalone widget.

For implementation examples see : [utils test.py](https://github.com/apache/superset/blob/66a4c94a1ed542e69fe6399bab4c01d4540486cf/tests/utils_tests.py#L181)
For insight into how superset processes the contents of this parameter see: [exploreUtils/index.js](https://github.com/apache/superset/blob/93c7f5bb446ec6895d7702835f3157426955d5a9/superset-frontend/src/explore/exploreUtils/index.js#L159) | +| `columns` | _array(string)_ | The **Breakdowns** widget | +| `groupby` | _array(string)_ | The **Group by** or **Series** widget | +| `limit` | _number_ | The **Series Limit** widget | +| `metric`
`metric_2`
`metrics`
`percent_metrics`
`secondary_metric`
`size`
`x`
`y` | _string_,_object_,_array(string)_,_array(object)_ | The metric(s) depending on the visualization type | +| `order_asc` | _boolean_ | The **Sort Descending** widget | +| `row_limit` | _number_ | The **Row limit** widget | +| `timeseries_limit_metric` | _object_ | The **Sort By** widget | The `metric` (or equivalent) and `timeseries_limit_metric` fields are all composed of either metric names or the JSON representation of the `AdhocMetric` TypeScript type. The `adhoc_filters` is composed of the JSON represent of the `AdhocFilter` TypeScript type (which can comprise of columns or metrics depending on whether it is a WHERE or HAVING clause). The `all_columns`, `all_columns_x`, `columns`, `groupby`, and `order_by_cols` fields all represent column names. From 014a55a2daa2eee20ea85091e0ae1a08b897eb9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Boisseau-Sierra?= Date: Wed, 27 Apr 2022 16:06:06 +0100 Subject: [PATCH 2/3] docs: Detail front-end development instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on the silly error that led to [this discussion](https://apache-superset.slack.com/archives/C014LS99C1K/p1650969237848999), we clarify that when modifying the front-end locally, one should access the Webpack dev servers, rather than Flask directly, to see the latest changes take effect. Signed-off-by: Étienne Boisseau-Sierra --- CONTRIBUTING.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8e6e3c6b6f0a..38c43961a6ee1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -571,7 +571,15 @@ There are three types of assets you can build: #### Webpack dev server -The dev server by default starts at `http://localhost:9000` and proxies the backend requests to `http://localhost:8088`. It's possible to change these settings: +The dev server by default starts at `http://localhost:9000` and proxies the backend requests to `http://localhost:8088`. + +Concretely, it means that you will want to: + +1. [run Superset locally](#flask-server) using Flask, on port `8088`, +2. in parallel, run the Webpack dev server locally on port `9000`, +3. access `http://localhost:9000` in your browser. (This will load the hot-reloading front-end assets from web-pack while redirecting back-end queries to Flask/Superset.) + +It's possible to change these settings: ```bash # Start the dev server at http://localhost:9000 From 94aab8f6815e9f76d3e58bfde911d7bf33547624 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Boisseau-Sierra?= Date: Thu, 28 Apr 2022 14:10:47 +0100 Subject: [PATCH 3/3] docs: Underline typical workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Étienne Boisseau-Sierra --- CONTRIBUTING.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 38c43961a6ee1..653cfe41a5f0c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -573,13 +573,20 @@ There are three types of assets you can build: The dev server by default starts at `http://localhost:9000` and proxies the backend requests to `http://localhost:8088`. -Concretely, it means that you will want to: +So a typical development workflow is the following: -1. [run Superset locally](#flask-server) using Flask, on port `8088`, -2. in parallel, run the Webpack dev server locally on port `9000`, -3. access `http://localhost:9000` in your browser. (This will load the hot-reloading front-end assets from web-pack while redirecting back-end queries to Flask/Superset.) +1. [run Superset locally](#flask-server) using Flask, on port `8088` — but don't access it directly,
+ ```bash + # Install Superset and dependencies, plus load your virtual environment first, as detailed above. + FLASK_ENV=development superset run -p 8088 --with-threads --reload --debugger + ``` +2. in parallel, run the Webpack dev server locally on port `9000`,
+ ```bash + npm run dev-server + ``` +3. access `http://localhost:9000` (the Webpack server, _not_ Flask) in your web browser. This will use the hot-reloading front-end assets from the Webpack development server while redirecting back-end queries to Flask/Superset: your changes on Superset codebase — either front or back-end — will then be reflected live in the browser. -It's possible to change these settings: +It's possible to change the Webpack server settings: ```bash # Start the dev server at http://localhost:9000