DevWorkflow

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).

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:

   git clone https://github.com/MyUser/lkpy.git
   cd lkpy
   

3. Add the LensKit upstream as a second origin:

   git remote add upstream https://github.com/lenskit/lkpy.git
   git fetch upstream
   

4. Set up the Conda bootstrap environment for setting up LensKit dev locks:

   conda env create -n lkboot -f https://raw.githubusercontent.com/lenskit/lkbuild/main/boot-env.yml
   

   See lkbuild for more details on this.

5. Solve the environment for LensKit development; the following builds with Python 3.10 and no extras besides development utilities:

   lkbuild dev-lock -v 3.10 --env-file
   

6. Create the Conda environment; for example on Linux:

   conda env create -n lkpy -f conda-linux-64.lock.yml
   

7. Activate the dev environment:

   conda activate lkpy
   

Step 1 is a one-time operation. Repeat steps 2 and 3 on each additional computer where you want to do LensKit development. Steps 4-7 should be repeated whenever the dev environment updates (the pyproject.toml file changes).

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