This is an automated email from the ASF dual-hosted git repository.
kristw pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-superset.git
The following commit(s) were added to refs/heads/master by this push:
new 96a0105 Update contributing.md with latest local dev instructions
(#6513)
96a0105 is described below
commit 96a0105f7a709ce2bc8e5722c146a7fd00276d4e
Author: Krist Wongsuphasawat <[email protected]>
AuthorDate: Tue Dec 11 13:45:50 2018 -0800
Update contributing.md with latest local dev instructions (#6513)
---
CONTRIBUTING.md | 104 +++++++++++++++++++++++++++++++-------------------------
1 file changed, 58 insertions(+), 46 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 568e527..c08a751 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -98,9 +98,9 @@ meets these guidelines:
7. If you are asked to update your pull request with some changes there's
no need to create a new one. Push your changes to the same branch.
-## Local development
+## Setup Local Environment for Development
-First, [fork the repository on
GitHub](https://help.github.com/articles/about-forks/), then clone it. You can
clone the main repository directly instead, but you won't be able to send pull
requests.
+First, [fork the repository on
GitHub](https://help.github.com/articles/about-forks/), then clone it. You can
clone the main repository directly, but you won't be able to send pull requests.
```bash
git clone [email protected]:your-username/incubator-superset.git
@@ -222,9 +222,11 @@ superset init
# Load some data to play with
superset load_examples
-# Start the Flask dev web server from inside the `superset` dir (but see below
for frontend asset compilation)
+# Start the Flask dev web server from inside the `superset` dir at port 8088
+# Note that your page may not have css at this point.
+# See instructions below how to build the front-end assets.
cd superset
-flask run -p 8080 --with-threads --reload --debugger
+FLASK_ENV=development flask run -p 8088 --with-threads --reload --debugger
```
#### Logging to the browser console
@@ -232,7 +234,7 @@ flask run -p 8080 --with-threads --reload --debugger
This feature is only available on Python 3. When debugging your application,
you can have the server logs sent directly to the browser console:
```bash
-superset runserver -d --console-log
+FLASK_ENV=development flask run -p 8088 --with-threads --reload --debugger
--console-log
```
You can log anything to the browser console, including objects:
@@ -243,41 +245,35 @@ app.logger.error('An exception occurred!')
app.logger.info(form_data)
```
-### Frontend assets
+### Frontend Assets
Frontend assets (JavaScript, CSS, and images) must be compiled in order to
properly display the web UI. The `superset/assets` directory contains all
NPM-managed front end assets. Note that there are additional frontend assets
bundled with Flask-Appbuilder (e.g. jQuery and bootstrap); these are not
managed by NPM, and may be phased out in the future.
First, be sure you are using recent versions of NodeJS and npm. Using
[nvm](https://github.com/creationix/nvm) to manage them is recommended.
-Install third-party dependencies listed in `package.json`:
+#### Prerequisite
-```bash
-# From the root of the repository
-cd superset/assets
+If needed, install yarn
-# If needed, install yarn, a replacement for `npm install`
+```bash
npm install -g yarn
-
-# Install dependencies
-yarn
```
-Finally, to compile frontend assets, run any of the following commands.
+#### Installing Dependencies
-```bash
-# Start a watcher that recompiles your assets as you modify them (reload your
browser to see changes)
-npm run dev
+Install third-party dependencies listed in `package.json`:
-# Compile the Javascript and CSS in production/optimized mode for official
releases
-npm run prod
+```bash
+# From the root of the repository
+cd superset/assets
-# Copy a conf file from the frontend to the backend
-npm run sync-backend
+# Install dependencies
+yarn install
```
-#### Webpack dev server
+#### Building
-Alternatively, you can run the Webpack dev server, which runs on port 9000 and
proxies non-asset requests to the Flask server on port 8088. After pointing
your browser to it, updates to asset sources will be reflected in-browser
without a refresh.
+You can run the Webpack dev server (in a separate terminal from Flask), which
runs on port 9000 and proxies non-asset requests to the Flask server on port
8088. After pointing your browser to it, updates to asset sources will be
reflected in-browser without a refresh.
```bash
# Run the dev server
@@ -290,7 +286,20 @@ npm run dev-server -- --port=9001
npm run dev-server -- --supersetPort=8081
```
-#### Upgrading NPM packages
+Alternatively you can use one of the following commands.
+
+```bash
+# Start a watcher that recompiles your assets as you modify them (but have to
manually reload your browser to see changes.)
+npm run dev
+
+# Compile the Javascript and CSS in production/optimized mode for official
releases
+npm run prod
+
+# Copy a conf file from the frontend to the backend
+npm run sync-backend
+```
+
+#### Updating NPM packages
After adding or upgrading an NPM package by changing `package.json`, you must
run `yarn install`, which will regenerate the `yarn.lock` file. Then, be sure
to commit the new `yarn.lock` so that other users' builds are reproducible. See
[the Yarn docs](https://yarnpkg.com/blog/2016/11/24/lockfiles-for-all/) for
more information.
@@ -309,20 +318,35 @@ export enum FeatureFlag {
}
```
+## Linting
+
+Lint the project with:
+
+```bash
+# for python
+tox -e flake8
+
+# for javascript
+cd superset/assets
+yarn install
+npm run lint
+```
+
## Testing
-All tests are carried out in
[tox](http://tox.readthedocs.io/en/latest/index.html)
-a standardized testing framework mostly for Python (though we also used it for
Javascript).
+### Python Testing
+
+All python tests are carried out in
[tox](http://tox.readthedocs.io/en/latest/index.html)
+a standardized testing framework.
All python tests can be run with any of the tox
[environments](http://tox.readthedocs.io/en/latest/example/basic.html#a-simple-tox-ini-default-environments),
via,
```bash
tox -e <environment>
```
-i.e.,
+For example,
```bash
-tox -e py27
tox -e py36
```
@@ -342,17 +366,17 @@ Note that the test environment uses a temporary directory
for defining the
SQLite databases which will be cleared each time before the group of test
commands are invoked.
-### JavaScript testing
+### JavaScript Testing
We use [Jest](https://jestjs.io/) and [Enzyme](http://airbnb.io/enzyme/) to
test Javascript. Tests can be run with:
```bash
-cd superset/assets/spec
-npm install
+cd superset/assets
+yarn install
npm run test
```
-### Integration testing
+### Integration Testing
We use [Cypress](https://www.cypress.io/) for integration tests. Tests can be
run by `tox -e cypress`. To open Cypress and explore tests first setup and run
test server:
@@ -373,18 +397,6 @@ npm run build
npm run cypress run
```
-### Linting
-
-Lint the project with:
-
-```bash
-# for python
-tox -e flake8
-
-# for javascript
-tox -e eslint
-```
-
## Translating
We use [Babel](http://babel.pocoo.org/en/latest/) to translate Superset. In
Python files, we import the magic `_` function using:
@@ -399,7 +411,7 @@ At runtime, the `_` function will return the translation of
the given string for
In JavaScript, the technique is similar: we import `t` (simple translation),
`tn` (translation containing a number).
```javascript
-import {t, tn } from '@superset-ui/translation';
+import { t, tn } from '@superset-ui/translation';
```
### Enabling language selection
