Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
228 lines (171 loc) · 6.7 KB

CONTRIBUTING.md

File metadata and controls

228 lines (171 loc) · 6.7 KB

Contribution Guidelines

As all source{d} projects, this project follows the source{d} Contributing Guidelines.

Additional Contribution Guidelines

In addition to the source{d} Contributing Guidelines, this project follows the following guidelines.

Content:

Changelog

This project lists the important changes between releases in the CHANGELOG.md file.

If you open a PR, you should also add a brief summary in the CHANGELOG.md mentioning the new feature, change or bugfix that you proposed.

Work With Superset Upstream

Superset version which we are based on is defined in Makefile.

To see which files are patched compare to upstream, run:

$ make diff-stat

To see diff with upstream, run:

$ make diff

Build Docker Image

The official Docker images of sourced-ui, used by source{d} CE are released at hub.docker.com/r/srcd/sourced-ui. You can also build yours running:

$ make build

The docker image name and tag are defined by the Makefile and can be overridden passing environment variables to the build target, example:

$ DOCKER_IMAGE_NAME=my/sourced-ui VERSION=local make build

will locally build an image called my/sourced-ui:local

Run source{d} CE For Development With Hot Reloading

Running source{d} CE in development mode will enable hot reloading at http://127.0.0.1:8088, so every change you perform in srcd or superset directories will trigger a refresh in your browser with the new code.

  1. Install the latest version of source{d} CE (see installation guide if needed)

  2. Build the srcd/sourced-ui:latest-dev development image, with the sources of sourced-ui:

    $ make build-dev

    It will take some time to be ready (~5min).

  3. Run the watcher.

    IMPORTANT note: Requirements for the watcher

    The watcher requires either inotify-tools (for Linux), or fswatch (for Linux and MacOS)

    • To install inotify-tools

      • in Ubuntu you can run: 
        $ sudo apt-get install inotify-tools

    • To install fswatch:

    ALTERNATIVE: If you can not use any watcher

    • If you cannot use any of these watchers, you can just run this:

      $ make set-override # to prepare the environment
$ make patch # needed EVERYTIME you change something in `srcd`
$ make clean # once you finish, to clean up everything.

    To watch for changes in srcd directory, run the local watcher in one tab, from your local sourced-ui root directory:

    $ make dev-prepare

    You can stop it pressing Ctrl+C. Once you do it, the patch will be automatically cleaned.

  4. Run sourced as usually (see execution guide if needed):

    # for repositories from GitHub organizations
$ sourced init orgs <orgs...> --token=<token>

# or, for repositories stored locally
$ sourced init local </path/to/repos>

    The first time you launch it, it will take some time to build all the UI assets, you can see the progress of the build from sourced-ui logs (see next step).

    It may happen that the hot reloading stops working with an error message Failed to compile that cannot be solved modifying the source code. It usually happens when switching between branches or stopping the watcher. To fix it, you only need to ensure the watcher is running, and init again.

  5. To see sourced-ui logs (with npm errors and such), run:

    $ sourced logs -f sourced-ui

Merging upstream

We base sourced-ui on release tags of superset instead of master.

Revert release branch changes (optional)

Release branches might contain cherry-picks or other commits that aren't presented in master branch or the next release branch. In such case it makes sense to revert them before applying changes from newer release.

All the releases have a topic in mailing list which contain common ancestor sha and list of commits for each release tag.

  1. Find common ancestor in the mailing list
  2. Find the last split commit 
    $ git log | grep git-subtree-split
  3. Checkout to split commit
  4. Revert commits 
    $ git revert --no-commit <common ancestor sha>...<release tag>
  5. Commit the revert as single commit 
    $ git commit -s -m "revert to upstream master from <release tag>"
  6. Merge revert into sourced-ui tree 
    $ git co master
$ git subtree merge -P superset HEAD@{1} --squash

Merge new release

$ git subtree merge -P superset <release-tag> --squash

After merge checklist

  • Re-create venv and re-install dependencies
  • Run linters 
    $ make patch
$ cd superset
$ TOXENV=black tox
$ TOXENV=flake8 tox
$ TOXENV=pylint tox
  • Merge migrations (if needed) 
    $ pip install -e .
$ superset db heads
$ superset db merge <head1> <head2>
  • Run tests 
    $ docker run --rm -p 6379:6379 redis
$ TOXENV=py36-sqlite tox
  • Build & check it with srcd-ce 
    $ make build
<run srcd-ce with this image>
  • Check if some changes to configuration should be ported, files to check:
    • superset/contib/docker
    • superset/superset/config.py
    • superset/.travis.yml
  • Update Makefile
  • Test upgrade