Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (136 loc) · 4.5 KB

CONTRIBUTING.md

File metadata and controls

199 lines (136 loc) · 4.5 KB

Contributing to LightlyStudio

Welcome! We are glad that you want to contribute to our project!

We welcome contributions of all kinds, including:

  • Bug fixes
  • Documentation improvements (README, docs folder, examples)
  • New features

After you have your changes ready, and you create a new pull request, a maintainer will review your PR, may ask for changes, suggest improvements, or approve once ready.

Development Quickstart

git clone git@github.com:lightly-ai/lightly_studio.git
cd lightly_studio/lightly_studio
make start

This will:

  • Install dependencies
  • Build the application
  • Start an example script

For starting it again, you can skip the build step by just calling make start-example.

Backend code lives in the lightly_studio subdirectory, frontend code in lightly_studio_view. To run static checks and unit tests use the following commands

# Backend
cd lightly_studio
make static-checks
make test

# Frontend
cd lightly_studio_view
make static-checks
make test

When updating the code please follow our coding guidelines in ./ai_guidelines. AI coding tools will be able to assist.

End-to-End Testing

We use Playwright for end-to-end testing. Tests need to be run separately for images and videos.

Testing with Images

First, start the e2e environment:

make -C lightly_studio start-e2e

Then run the tests:

cd lightly_studio_view
npm run test:e2e

Testing with Videos

First, start the e2e environment with videos:

make -C lightly_studio start-e2e-with-videos

Then run the video tests:

cd lightly_studio_view
npm run test:e2e-videos

Documentation

Documentation is in the docs folder. To build the documentation, move to the docs folder and run:

make docs

This builds the documentation in the docs/site folder.

Docs can be served locally with:

make serve

Writing Documentation

The documentation source is in docs/docs. The documentation is written in Markdown (MyST flavor). For more information regarding formatting, see:

Development Environment Setup

Requirements

  • Python 3.9+
  • Uv version 0.8.17+
  • Node.js 22.11+
  • Access to Google Cloud Platform (request permissions from @IgorSusmelj)

Clone the Repository with Test Data

Clone the example dataset repository inside the backend subdirectory lightly_studio. It contains sample data used during development.

cd lightly_studio
git clone https://github.com/lightly-ai/dataset_examples

Define Environment Variables

We recommend using the .env file to set up environment variables. Start by copying .env.example file to .env:

cd lightly_studio
cp .env.example .env

Now edit the .env file:

  • Request the LIGHTLY_STUDIO_LICENSE_KEY from a Lightly developer and set its value in the file.
  • Optionally change the EXAMPLES_* paths to point to data on your machine. You can leave the defaults to use the cloned dataset examples data.

Run Examples

Choose a script in lightly_studio/src/lightly_studio/examples directory and run it like this:

cd lightly_studio
uv run src/lightly_studio/examples/example.py

Start the Backend

Navigate to the backend lightly_studio directory and run:

cd lightly_studio
make start

Start the Frontend

In a new terminal tab, navigate to the lightly_studio_view directory and copy the environment file:

cd lightly_studio_view
cp .env .env.local

Then, define the following variables in your .env.local file:

PUBLIC_SAMPLES_URL=http://localhost:8001/images
PUBLIC_LIGHTLY_STUDIO_API_URL=http://localhost:8001/

Finally, start the frontend:

npm run dev

Exploring the Makefile

The Makefile includes several helpful commands. Here are some commonly used ones:

Run tests:

make test

Format code:

make format

You can explore more available commands directly in the Makefile.

Contributor License Agreement (CLA)

To contribute to this repository, you must sign a Contributor License Agreement (CLA). This is a one-time process done through GitHub when you open your first pull request. You will be prompted automatically.

By signing the CLA, you agree that your contributions may be used under the terms of the project license.