Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
255 lines (168 loc) · 9.48 KB

DEVELOPMENT.md

File metadata and controls

255 lines (168 loc) · 9.48 KB

Developer's Guide

Setting Up Your macOS Development Environment

This section shows you how to set up an isolated virtual environment using pyenv and virtualenvwrapper. If you are new to pyenv, you can install it via brew with

brew install pyenv

Next, install a phoenix-supported Python version, e.g., 3.10.8, with

export PHOENIX_PYTHON_VERSION=<your-supported-python-version>
pyenv install $PHOENIX_PYTHON_VERSION

Set the global pyenv version with

pyenv global $PHOENIX_PYTHON_VERSION

Install virtualenvwrapper with

pip install virtualenvwrapper

Create a new virtual environment with

mkvirtualenv phoenix-env

Install phoenix in development mode (using the -e flag) and with development dependencies (using the [dev] extra) by running

pip install -e '.[dev]'

from the repository root.

Running Scripts with hatch

hatch is the project management tool used to build phoenix. After installing and activating the phoenix-env virtual environment, view the project environments, dependencies and scripts defined in pyproject.toml with

hatch env show

Scripts belonging to the various environments can be run with

hatch run <env-name>:<script-name>

For example, you can check types with

hatch run type:check

You can fix styles with

hatch run style:fix

You can run tests with coverage with

hatch run test:coverage

The following resources are helpful to learn more about the capabilities of hatch and to familiarize yourself with the CLI.

Installing Pre-Commit Hooks

We recommend to install project pre-commit hooks with

pre-commit install

Once installed, the pre-commit hooks configured in .pre-commit-config.yaml will automatically run prior to each git commit. Pre-commit hooks can be skipped by passing the -n/ --no-verify flag to the git commit command.

Building the phoenix Package

To build phoenix, run

hatch build

If successful, a source distribution (a tarball) and a Python wheel will appear in the dist folder at the repo base directory.

Installing a phoenix Build

We recommend using a separate virtual environment (e.g., phoenix-test-env) for installing and testing the builds created above.

To install phoenix from the source distribution (i.e., tarball), run

pip install /path/to/source/distribution/tarball.tar.gz

To install phoenix from the Python wheel, you must first install wheel with

pip install wheel

Then run

pip install /path/to/wheel.whl

(You should only install one of the source distribution or the wheel at a time.)

To make sure everything works, install jupyter with

pip install jupyter

and run the notebooks in the examples directory.

Setting Up Your Windows Test Environment

It is occasionally necessary to manually test a phoenix build or to run phoenix from source on Windows. The following instructions enable macOS developers who do not have a PC to quickly set up a Windows Python environment in a cloud or local virtual machine.

Selecting a Virtualization Option

We recommend to use a virtual machine either with Microsoft Azure (a cloud virtual machine) or using the Parallels Desktop app (a local virtual machine). Which option you select will depend on your hardware and whether you wish to run a remote IDE. The following resources are helpful to make a decision:

At the time of this writing in December 2022,

  • Windows 11 is the only Windows OS with a supported ARM version,
  • JetBrains does not support remote development on Windows servers,
  • VSCode supports remote development on certain Windows versions not including Windows 11.

Hence, if you are a macOS developer using an Apple Silicon machine and you wish to use a remote interpreter, running a Windows VM locally is not straightforward and we recommend you use a Windows VM on Azure.

If you elect to use an Azure VM, we recommend that you select a non-headless OS (we use Windows Server 2019), configure an inbound port rule for RDP on port 3389 while creating the VM and screenshare with your VM using Microsoft Remote Desktop, which can be downloaded from the Apple App Store. This will enable you to configure an SSH server on the VM for remote development.

Installing Python and phoenix

The following instructions assume you have created a Windows virtual machine either locally or in the cloud. These instructions have been tested on Windows Server 2019 and assume you are using Powershell.

Install chocolatey, a package manager for Windows, by following the instructions here.

Open a new shell and run

choco install nvm pyenv-win git

Open a new shell and install the latest long-term supported version of node using

nvm install lts

Activate this version using

nvm use lts

Open a new shell and confirm that node and npm are available with

node --version
npm --version

Install your desired Python version with

$env:PHOENIX_PYTHON_VERSION = "desired-python-version"
pyenv install $env:PHOENIX_PYTHON_VERSION

Set the global pyenv version with

pyenv global $env:PHOENIX_PYTHON_VERSION

Install virtualenvwrapper-win with

pip install virtualenvwrapper-win

Create a virtual environment called phoenix-env with

mkvirtualenv phoenix-env

Activate your virtual environment. You can now install a phoenix build. Alternatively, if you wish to run phoenix from source, clone the repo and install phoenix in development mode with

pip install -e '.[dev]'

Configuring a Remote Interpreter

If you wish to use a remote SSH interpreter (e.g., via VSCode), you must install and run an SSH server on your Windows VM. We recommend to install OpenSSH Server by navigating to Settings > Apps > Manage optional features > Add a feature, selecting OpenSSH Server in the list and clicking Install. To start the SSH server, navigate to Control Panel > System and Security > Administrative Tools > View local services, select OpenSSH Server and press Start. If you wish to configure the server to start automatically on startup, select Actions > Properties while OpenSSH Server is selected from the list (or just double-click on OpenSSH Server), select Automatic in the Startup type dropdown and hit Apply.

You must also ensure that port 22 of your Windows VM is reachable by your SSH client.

  • If using an Azure VM, this can be accomplished by defining an appropriate inbound port rule for TCP on port 22 either during creation of the virtual machine or after creation in the VM's networking settings.
  • If using Parallels Desktop, navigate to Preferences > Network and define a port forwarding rule for TCP on destination port 22.

Troubleshooting

  • In our experience, the workon command familiar to users of virtualenvwrapper may not properly run on Windows with virtualenvwrapper-win. In order to activate a virtual environment, you can manually run the appropriate activation script (activate.ps1 if using Powershell) typically located in $env:USERPROFILE\Envs\<env-name>\Scripts.

Publishing a New Release

To publish a new release, follow the steps below.

  1. Make sure your branch is up-to-date with main
  2. Update the version number in src/phoenix/__init__.py
  3. By default, the web app is not re-built. Run npm run build in the app directory to re-build the web app.
  4. clear the dist folder just to be safe.
  5. Build the package with hatch build
  6. Publish the package with hatch publish
  7. Commit the changes using the version number as the message (e.x. 0.0.1) and get it into to main
  8. Using the GitHub CLI, create a draft release with gh release create <version> --generate-notes --draft
  9. Edit the release notes as needed and publish the release. This will trigger a slack notification to the #phoenix-releases channel.
  10. A conda-forge PR will be automatically created. If the PR is not created, you can create it manually by following the instructions here.