Skip to content

DevWorkflow

Jump to bottom
Michael Ekstrand edited this page Oct 27, 2024 · 8 revisions

Development Workflow

The LensKit development workflow is based on branches and pull requests. With few exceptions, the main repository (this one) only contains released branches; all in-progress work is in branches in developer forks.

We strongly recommend that you not develop on main, even in your own fork. Develop on a branch, push the branch to your fork, and submit a PR from there. Keep your main tracking upstream main.

Terms

Upstream: the main LensKit repository (this one)

main: the main development branch

fork: your own fork of the repository (e.g. https://github.com/mdekstrand/lkpy).

Required Software

The easiest way to get started is either to use your editor or IDE's GitHub support, or to use the GitHub CLI. We manage development dependencies with Pixi, so you need to install that as well. You also need Git.

Mac OS

All required packages are available in Homebrew:

$ brew install git gh pixi

Windows

All required dependencies are available via WinGet:

PS> winget install Git.Git
PS> winget install GitHub.cli
PS> winget install prefix-dev.pixi

You need to restart your terminal after running these commands to ensure your search paths are updated.

Linux

Git is available from your system package manager; follow install instructions on their home pages for GitHub CLI and Pixi.

First Time

Here is what you need to do to be ready to develop on LensKit:

  1. Fork LensKit to your GitHub account (click the 'Fork' button)

  2. Clone your repository and set up upstream:

    gh repo clone myuser/lkpy

  3. Install the dev environment:

    pixi shell -e dev-full

  4. Set up the pre-commit hooks to help ensure code quality before submitting PRs:

    pixi run -e dev-full pre-commit install

Note

The dev-full environment does not work on Windows, as hpfrec is only packaged for Linux and macOS at present. Use the dev-core environment instead.

You can then run commands within the dev environment(s) with pixi run, and spawn a new shell for LensKit work with:

pixi shell -e dev-full

The pixi shell line will install the environment and spawn a new shell with it active. You can then run commands like pytest from this shell. Running exit will return you to the parent shell.

You can also set the installed environment (under .pixi/envs/dev-full or .pixi/envs/dev-core) as your interpreter in VS Code.

Starting a Change Set

Here are the steps to start a new set of changes:

  1. Update your main branch:

    git checkout main
git pull
git pull upstream main
git push

  2. Create your new branch:

    git checkout -b feature/my-new-thing

  3. Do your work, commit changes, etc.

  4. Push:

    git push -u origin feature/my-new-thing

  5. Create a pull request by visiting https://github.com/lenskit/lkpy and creating a PR from your new branch.

  6. Repeat 3 and 4 as needed to fix issues, address review comments, etc.

  7. We merge the PR!

Running the Tests

It's useful to run the tests locally, to make sure that the code works at least on your machine before submitting the PR.

python -m pytest tests

Clone this wiki locally