From 4e52a4ca1243c0ceaaffb4674c8887e3a8ad933c Mon Sep 17 00:00:00 2001 From: augray Date: Tue, 17 Dec 2024 11:13:18 -0800 Subject: [PATCH 1/2] update docs --- developer-docs/README.md | 100 ++++++------------ docs/sematic-vs.md | 2 +- .../examples/testing_pipeline/__main__.yaml | 7 +- 3 files changed, 39 insertions(+), 70 deletions(-) diff --git a/developer-docs/README.md b/developer-docs/README.md index 2303ee775..1eb090f05 100644 --- a/developer-docs/README.md +++ b/developer-docs/README.md @@ -6,16 +6,13 @@ and are published to https://docs.sematic.dev/ ## Setup The developer tools need to be installed by running this command once (and subsequently -whenever `requirements/ci-requirements.txt`) will be updated: +whenever `uv.lock` will be updated): ```bash -$ make install-dev-deps +$ make py-prep ``` - -### Bazel installation - -Be sure to install a compatible version of bazel: `sudo apt update && sudo apt install bazel-6.1.1` - -You may also want to add the following to your .bashrc: `export USE_BAZEL_VERSION=6.1.1` +This will result in a python virtual environment prepared at `./.venv`. You must +activate into that virtual environment with `source .venv/bin/activate` if you +wish to have an interpreter with Sematic and its dependencies installed. ## Testing @@ -31,7 +28,7 @@ In order to ensure the PR review goes swiftly, please: - Add a comprehensive description to your PR - Ensure your code is properly formatted and type checked - - Make sure you have the dev tools installed by running `make install-dev-deps` (you only ever need to do this once) + - Make sure you have the dev tools installed by running `make py-prep` (you only ever need to do this once) - Use `make pre-commit` to run the linter and code formatter - Use `make update-schema` to make sure any DB changes you made are accounted for - Make sure the CircleCI build passes for your branch (linked in the checks section at the bottom of the GitHub PR page) @@ -63,23 +60,29 @@ When developing, we often need to switch the Server where we submit pipelines, sometimes bundled together with other settings as well. In order to avoid constantly editing this file manually, we can define one file per environment or profile, under the names `~/.sematic/settings.yaml.`, and switch -between them using `bazel run //tools:switch-settings -- `. +between them using `cp ~/.sematic/settings.yaml. ~/.sematic/settings.yaml`. -This actually copies these profile files over the main settings file. Example: +Example: ```bash -$ bazel run //tools:switch-settings -- prod1 -[...] -Copying previous settings to /Users/tudorscurtu/.sematic/settings.yaml_bck -Copying /Users/tudorscurtu/.sematic/settings.yaml.prod1 to /Users/tudorscurtu/.sematic/settings.yaml - -Successfully switched to prod1! - +$ cp ~/.sematic/settings.yaml ~/.sematic/settings.yaml.prod1 +$ cp ~/.sematic/settings.yaml ~/.sematic/settings.yaml.prod2 +$ vim ~/.sematic/settings.yaml.prod1 # edit whatever you need to +$ vim ~/.sematic/settings.yaml.prod2 # edit whatever you need to +$ # To use prod1: +$ cp ~/.sematic/settings.yaml.prod1 ~/.sematic/settings.yaml $ sematic settings show Active user settings: SEMATIC_API_ADDRESS: https:// SEMATIC_API_KEY: +$ # To use prod2: +$ cp ~/.sematic/settings.yaml.prod2 ~/.sematic/settings.yaml +$ sematic settings show +Active user settings: + +SEMATIC_API_ADDRESS: https:// +SEMATIC_API_KEY: ``` ## Building the Wheel @@ -88,7 +91,7 @@ If you want to build the wheel from source, do: ```bash $ make ui -$ make wheel +$ make uv-wheel ``` ## SQLite vs Postgres Migrations @@ -115,10 +118,8 @@ performed in order, without skipping any. If any errors occur, you must fix them and then go back and redo all the steps that have been affected by the changes. -1. Announce internally that a `main` merge freeze has started. - 1. Bump the version in: - - `wheel_constants.bzl` - `wheel_version_string` + - `pyproject.yaml` - `version` - `helm/sematic-server/Chart.yaml` - `appVersion` - `sematic/versions.py` - `CURRENT_VERSION`; bump `MIN_CLIENT_SERVER_SUPPORTS` if there are any TODOs mentioning this should be done @@ -138,12 +139,12 @@ changes. 1. Build the wheel: ```bash - $ make wheel + $ make uv-wheel ``` 1. Test the Server wheel locally for all supported versions of Python. - 1. Copy the wheel from `bazel-bin/sematic/sematic-*.whl` into a scratch + 1. Copy the wheel from `./dist/sematic-*.whl` into a scratch directory. 1. For each supported version of Python, use a virtual env to test: @@ -159,7 +160,7 @@ changes. 1. Test the [internal Helm charts](/helm/sematic-server) deployment. - 1. **Test an upgrade deployment** in the `stage` environment, **where the previous + 1. **Test an upgrade deployment** in a staging environment, **where the previous version is already deployed**, use [`serve-dev`](https://github.com/sematic-ai/infrastructure/tree/main/bin) to upgrade the deployment with a Docker image built on-the-fly from the current release commit. @@ -175,20 +176,13 @@ changes. 1. Smoke test new features that were included or significantly updated in the release. - 1. Ensure you have a compatible version of bazel: - - ```bash - $ export USE_BAZEL_VERSION=6.1.1 - $ sudo apt update && sudo apt install bazel-6.1.1 - ``` - 1. Run the Testing Pipeline with the test cases listed below on this deployment, and check that it completes successfully, while perusing its outputs and logs to check that they render correctly. ```bash $ # STAGE: - $ bazel run sematic/examples/testing_pipeline:__main__ -- \ + $ sematic run --build sematic/examples/testing_pipeline/__main__.py -- \ --cloud \ --detach \ --max-parallelism 10 \ @@ -198,19 +192,16 @@ changes. --sleep 10 \ --spam-logs 1000 \ --fan-out 10 \ - --raise-retry 0.7 \ + --raise-retry 0.1 \ --external-resource \ --expand-shared-memory \ - --mount-host-path /tmp /test \ - --mount-host-path /tmp /test2 \ --cache-namespace test \ --images \ --virtual-funcs \ --fork-subprocess return 0 \ --fork-subprocess exit 0 \ --fork-subprocess exit 1 \ - --fork-subprocess signal 2 \ - --fork-subprocess signal 15 + --fork-subprocess signal 2 ``` 1. Test client backwards compatibility. Install the version of Sematic that matches @@ -219,11 +210,11 @@ changes. the new Server. ```bash $ sematic version # check that the correct min version is installed - $ STAGE: + $ # STAGE: $ sematic run examples/mnist/pytorch ``` - 1. **Test a clean installation** in the same `stage` environment. + 1. (Optional) **Test a clean installation** in the same `stage` environment. ```bash $ # STAGE: $ helm uninstall sematic-server -n stage @@ -237,7 +228,7 @@ changes. aspect as well. ```bash $ # STAGE: - $ bazel run sematic/examples/testing_pipeline:__main__ + $ sematic run --build sematic/examples/testing_pipeline/__main__.py ``` 1. Test publishing the wheel. Check if the generated webpage on `test.pypi.org` is @@ -271,17 +262,15 @@ changes. 1. Add the git tag. ```bash - $ export RELEASE_VERSION=v$(python3.9 ./sematic/versions.py) + $ export RELEASE_VERSION=v$(python3 ./sematic/versions.py) $ git tag $RELEASE_VERSION $ git push origin $RELEASE_VERSION ``` -1. Announce internally that the `main` merge freeze is over. - 1. Build and push the Server Docker image. Use the Dockerfile at `docker/Dockerfile.server`. ```bash - $ TAG=v$(python3.9 ./sematic/versions.py) make release-server + $ TAG=v$(python3 ./sematic/versions.py) make release-server ``` 2. Next you can generate the Helm package and publish it to the Helm repository. @@ -331,19 +320,6 @@ changes. repo. Commit and push all of these to a new release branch, and create a PR for the change based on `gh-pages`. Wait for approval, and merge it. -1. Deploy this new official release to the `stage` environment, in order to leave it in a - consistent and expected state, and to test the actual commands users will be using to - deploy the release. - ```bash - $ # Run this step if it has never been done before - $ helm repo add sematic-ai https://sematic-ai.github.io/helm-charts - - $ # STAGE: - $ helm repo update - $ helm upgrade sematic-server sematic-ai/sematic-server -n stage -f /path/to/stage_values.yml - $ helm list -n stage # check that the expected APP VERSION was deployed - ``` - 1. Finally, draft the release on GitHub, from [the tag you previously committed](https://github.com/sematic-ai/sematic/tags): - Pick the `"previous tag"` from the dropdown to refer to the previous release. @@ -382,11 +358,3 @@ cases, instead of performing the release from the `main` branch, we: - cherry-pick the commits we want to include - follow all the other steps from the [Releasing](#releasing) section - switch to the `main` branch, make a commit that contains the previous version - increase and reconciles the changelog, and merge a PR with this commit - -## Updating the CircleCi Image - -The image used for most of our CircleCi steps is built using `docker/Dockerfile.ci`. -After updating it, open a PR with the change, push the image to Dockerhub using the PR -number as a tag (in order to be able to maintain a history, and revert, if necessary), -and update the `SEMATIC_CI_IMAGE` env var in the CircleCi project settings. diff --git a/docs/sematic-vs.md b/docs/sematic-vs.md index d9841c6b4..5cb43e09b 100644 --- a/docs/sematic-vs.md +++ b/docs/sematic-vs.md @@ -20,7 +20,7 @@ rest. ### Lowest barrier to entry -In 2023, with all the great technology there is out there, it is entirely +In 2025, with all the great technology there is out there, it is entirely possible to provide an amazing turn-key onboarding experience with a very low barrier to entry for all sets of skills, from beginner padawan to advanced ninja. diff --git a/sematic/examples/testing_pipeline/__main__.yaml b/sematic/examples/testing_pipeline/__main__.yaml index ad4508d4f..11c5b2ec1 100644 --- a/sematic/examples/testing_pipeline/__main__.yaml +++ b/sematic/examples/testing_pipeline/__main__.yaml @@ -1,10 +1,11 @@ version: 1 -base_uri: "sematicai/sematic-worker-base:latest@sha256:bea3926876a3024c33fe08e0a6b2c0377a7eb600d7b3061a3f3f39d711152e3c" +base_uri: "sematicai/sematic-worker-base:cuda@sha256:6cbedeffdbf8ef0e5182819b4ae05a12972f61a4cd862fe41e4b3aaca01888da" build: platform: "linux/amd64" requirements: "requirements.txt" data: ["resources"] + src: ["//sematic"] push: - registry: "558717131297.dkr.ecr.us-west-2.amazonaws.com" # update this to your own registry - repository: "sematic-dev" # update this to your own repository + registry: "us-central1-docker.pkg.dev/core-400321/main" # update this to your own registry + repository: airtrain-pipeline # update this to your own repository tag_suffix: "main_example" From 0f9301c545cf453b36ab328e8ac0235cedf6e588 Mon Sep 17 00:00:00 2001 From: augray Date: Tue, 17 Dec 2024 11:17:23 -0800 Subject: [PATCH 2/2] remove bazel tips --- developer-docs/tips-for-bazel.md | 146 ------------------------------- 1 file changed, 146 deletions(-) delete mode 100644 developer-docs/tips-for-bazel.md diff --git a/developer-docs/tips-for-bazel.md b/developer-docs/tips-for-bazel.md deleted file mode 100644 index 1344b23a6..000000000 --- a/developer-docs/tips-for-bazel.md +++ /dev/null @@ -1,146 +0,0 @@ -# Bazel Tips - -You can execute most things in this repo with bazel. Here are some particularly useful examples: - -## Testing - -This will execute all tests, including all supported versions of python. -``` -bazel test //sematic/... -``` - -This will run a specific test (in this case the API client test), on the default python version. -The target path is the file path to the python package where the test lives (`sematic.tests` -in the example below), followed by a colon and the name of the python module for the test -(`test_api_client` in this example). -``` -bazel run //sematic/tests:test_api_client -``` - -This will run a specific test (in this case the API client test), on the python version indicated -by the `_py3_X` (python 3.9 in the example below). -``` -bazel run //sematic/tests:test_api_client_py3_9 -``` - -If you are using VSCode, you can use the VSCode debugger with bazel while testing. First, you -need to add this to your VSCode `launch.json` configurations: -``` - { - "name": "Python: Attach", - "type": "python", - "request": "attach", - "port": 5724, - "host": "localhost", - "pathMappings": [ - { - "localRoot": "${workspaceFolder}", - "remoteRoot": "." - } - ] - }, -``` - -Once you've done that, you can debug tests with bazel by: -- Running your test with `DEBUGPY=1`: `DEBUGPY=1 bazel run //sematic/tests:test_api_client` -- once the test has paused (should pause very quickly), execute the `Python: Attach` debug -configuration from your VSCode debug panel. It should attach to the debugger. -- While the debugger is running, you can use all the debugger features you'd expect: breakpoints, -stepping, variables and watch views, stack navigation, etc.. - - -## IPython -You can open an iPython shell that contains the dependencies for any `sematic_py_lib`. -This is only supported for Linux platforms: -``` -$ bazel run //sematic:api_client_ipython # build //sematic:api_client and open a shell -In [1]: from sematic import api_client as api -``` - -You can also do this for specific versions of python by adding a `_py3_X_` between the -name of the lib target and the `ipython`: -``` -$ bazel run //sematic:api_client_py3_9_ipython # build target and open a py3.9 shell -In [1]: from sematic import api_client as api -``` - -## Sematic examples -You can run Sematic examples by running one of the targets created with the -`sematic_example` build macro: -``` -$ bazel run //sematic/examples/liver_cirrhosis:liver_cirrhosis -``` - -You can do this using a specific interpreter as well with a `_py3_X` suffix: -``` -$ bazel run //sematic/examples/liver_cirrhosis:liver_cirrhosis_py3_9 -``` - -You can also open an ipython interpreter into the environment for the example: -``` -$ bazel run //sematic/examples/liver_cirrhosis:liver_cirrhosis_py3_9_ipython -In [1]: from sematic.examples.liver_cirrhosis import * -``` - -## Sematic CLI -For the sematic CLI (as well as any other `sematic_py_binary`), you can run them -by just running their targets: - -``` -$ bazel run //sematic/cli:main -- --help -``` - -You can also do *this* with specific python interpreters: -``` -$ bazel run //sematic/cli:main_py3_9 -- --help -``` - -## Miscellaneous -To clear the Bazel cache, run: - -``` -$ bazel clean --expunge -``` - -## Troubleshooting - -### CPP Toolchain Error -If you get an error message like: - -`"No matching toolchains found for types @bazel_tools//tools/cpp:toolchain_type"`, -this means bazel can't find your c++ tooling. This can either be due to the fact that -bazel can't find ANY c++ tooling OR the fact that it can't find c++ tooling suitable -for building linux docker images. - -#### Totally missing c++ tooling -``` -$ bazel test --toolchain_resolution_debug=@bazel_tools//tools/cpp:toolchain_type //sematic/... -``` - -On Macs this is often due to a problem with Xcode. If you are on a Mac: -- Make sure you have xcode installed -- Execute `sudo xcodebuild -license` and agree to the license -- If the above command gives you an error about CommandLineTools and won't show -the License, try [this](https://stackoverflow.com/a/72115137/2540669) - -#### Missing c++ tooling for cross platform docker images -Try this: -``` -$ bazel test --@io_bazel_rules_docker//transitions:enable=false //sematic/... -``` - -This flag will NOT enable actually building images for remote execution -cross-platform, but WILL most likely unblock your ability to run tests. -If this doesn't work, please try to debug what you can and update these -tips! - -### Docker credential error - -If you get an error message like: -``` -error getting credentials - err: exec: "docker-credential-desktop": -``` -Then you likely need to install Docker. On Mac, some people have found -that even if Docker does not work for them on their Mac, they need to -do this install. If you are in this situation, you may also need to add -`/Applications/Docker.app/Contents//Resources/bin` to your `PATH`.