superset-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kri...@apache.org
Subject [incubator-superset] branch master updated: Update contributing.md with latest local dev instructions (#6513)
Date Tue, 11 Dec 2018 21:45:58 GMT
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 <krist.wongz@gmail.com>
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 git@github.com: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


Mime
View raw message