Skip to content

Latest commit

 

History

History
301 lines (222 loc) · 7.27 KB

DEVELOPMENT.md

File metadata and controls

301 lines (222 loc) · 7.27 KB

Install BentoML from source

Ensure you have git, python and pip installed, BentoML supports python 3.6, 3.7, and 3.8

$ python --version
$ pip --version

Download the source code from BentoML's Github repository:

$ git clone https://github.com/bentoml/BentoML.git
$ cd BentoML

Install BentoML with pip in editable mode:

pip install --editable .

This will make bentoml available on your system which links to the sources of your local clone and pick up changes you made locally.

Test the BentoML installation:

$ bentoml --version
import bentoml
print(bentoml.__version__)

Install BentoML from other forks or branches

The pip command support installing directly from remote git repository. This makes it easy to try out new BentoML feature that has not been released, test changes in a pull request. For example, to install BentoML from its master branch:

pip install git+https://github.com/bentoml/BentoML.git

Or to install from your own fork of BentoML:

pip install git+https://github.com/{your_github_username}/BentoML.git

You can also specify what branch to install from:

pip install git+https://github.com/{your_github_username}/BentoML.git@{branch_name}

How to run unit tests

  1. Install all test dependencies:
$ pip install -e ".[test]"
  1. Run all unit tests with current python version and environment
$ ./ci/unit_tests.sh

Optional: Run unit test with all supported python versions

Make sure you have conda installed:

$ conda --version

Bentoml tox file is configured to run in muiltple python versions:

$ tox

If you want to run tests under conda for specific version, use -e option:

$ tox -e py37
// or
$ tox -e py36

Run BentoML with verbose/debug logging

Add the following lines to the Python code that invokes BentoML:

from bentoml.configuration import set_debug_mode
set_debug_mode(True)

And/or set the BENTOML_DEBUG environment variable to TRUE:

$ export BENTOML_DEBUG=TRUE

And/or use the --verbose option when running bentoml CLI command, e.g.:

$ bentoml get IrisClassifier --verbose

Style check and auto-formatting your code

Make sure to install all dev dependencies:

$ pip install -e ".[dev]"

Run linter/format script:

$ ./dev/format.sh

$ ./dev/lint.sh

Optional: Running mypy for better type annotation

Make sure to install mypy

You might have to install stubs before running:

$ mypy --install-types

After updating/modifying codebase (e.g: bentoml/yatai/client), run mypy:

$ mypy bentoml/yatai/client

How to edit, run, build documentation site

Install all dev dependencies:

$ pip install -e ".[dev]"

To build documentation for locally:

$ ./docs/build.sh

Modify *.rst files inside the docs folder to update content, and to view your changes, run the following command:

$ python -m http.server --directory ./docs/build/html

And go to your browser at http://localhost:8000

If you are developing under macOS or linux, we also made a script that watches docs file changes, automatically rebuild the docs, and refreshes the browser tab to show the change (macOS only):

How to run spell check for documentation site

Install all dev dependencies:

$ pip install -e ".[dev]"

Install spellchecker dependencies:

$ make install-spellchecker-deps

To run spellchecker locally:

$ make spellcheck-doc

macOS

Make sure you have fswatch command installed:

brew install fswatch

Run the watch.sh script to start watching docs changes:

$ ./docs/watch.sh

Linux

Make sure you have inotifywait installed

sudo apt install inotify-tools

Run the watch.sh script to start watching docs changes:

$ ./docs/watch.sh

How to debug YataiService GRPC server

Install all dev dependencies:

$ pip install -e ".[dev]"

Install grpcui:

$ go get github.com/fullstorydev/grpcui
$ go install github.com/fullstorydev/grpcui/cmd/grpcui

Start Yatai server in debug mode:

$ bentoml yatai-service-start --debug

In another terminal session run grpcui:

$ grpcui -plain text localhost:50051

gRPC Web UI available at http://127.0.0.1:60551/...

Navigate to the URL from above

How to use YataiService helm chart

BentoML also provides a Helm chart under bentoml/yatai-chart for installing YataiService on Kubernetes.

Running BentoML Benchmark

BentoML has moved its benchmark to bentoml/benchmark.

How to run and develop BentoML Web UI

Make sure you have yarn installed: https://classic.yarnpkg.com/en/docs/install

Install all npm packages required by BentoML Web UI:

# install npm packages required by BentoML's Node.js Web Server
cd {PROJECT_ROOT}/bentoml/yatai/web/
yarn

# install npm packages required by BentoML web frontend
cd {PROJECT_ROOT}/bentoml/yatai/web/client/
yarn

Build the Web Server and frontend UI code:

cd {PROJECT_ROOT}/bentoml/yatai/web/
npm run build

How to test GitHub Actions locally

If you are developing new artifacts or modify GitHub Actions CI (adding integration test, unit tests, etc), use nektos/act to run Actions locally.

Creating Pull Request on Github

  1. Fork BentoML project on github and add upstream to local BentoML clone:
$ git remote add upstream [email protected]:YOUR_USER_NAME/BentoML.git

  1. Make the changes either to fix a known issue or adding new feature

  2. Push changes to your fork and follow this article on how to create a pull request on github. Name your pull request with one of the following prefixes, e.g. "feat: add support for PyTorch". This is based on the Conventional Commits specification

    • feat: (new feature for the user, not a new feature for build script)
    • fix: (bug fix for the user, not a fix to a build script)
    • docs: (changes to the documentation)
    • style: (formatting, missing semicolons, etc; no production code change)
    • refactor: (refactoring production code, eg. renaming a variable)
    • perf: (code changes that improve performance)
    • test: (adding missing tests, refactoring tests; no production code change)
    • chore: (updating grunt tasks etc; no production code change)
    • build: (changes that affect the build system or external dependencies)
    • ci: (changes to configuration files and scripts)
    • revert: (reverts a previous commit)

  3. Once your pull request created, an automated test run will be triggered on your branch and the BentoML authors will be notified to review your code changes. Once tests are passed and reviewer has signed off, we will merge your pull request.

Optional: Install git hooks to enforce commit format

Run ./dev/install_git_hooks.sh to install git hooks to automate commit format enforcement described above.