Skip to content

Setup and Basics

Installation

Cloning Repo

First fork the lineapy repo. Then, clone the forked repo to your development environment:

cd <PATH-TO-DESIRED-LOCATION>
git clone <URL-TO-FORKED-REPO>

To keep the forked repo in sync with the original one, set an "upstream":

git remote add upstream https://github.com/LineaLabs/lineapy.git

Setting up Virtual Environment

Note

Here, we use venv for virtual environment setup because it comes with Python core distribution. If you prefer a different option (e.g., conda), you can skip this section.

When done cloning, move into the repo and initiate a virtual environment:

cd <FORKED-REPO-NAME>
python -m venv env

where <FORKED-REPO-NAME> is lineapy unless modified during/after forking.

This creates env/ subfolder inside the repo, and you can activate the associated virtual environment like so:

source env/bin/activate

To deactivate the virtual environment, you can type:

deactivate

Warning

If you use a different name for this virtual environment subfolder, you will need to register the new name in several config files including .gitignore, .flake8, pyproject.toml lest it will create friction for other workflows such as pre-commit. Hence, we strongly recommend you name the subfolder env/ as instructed above.

Installing Dependencies

Once the virtual environment is activated, install packages necessary for running and developing lineapy:

pip install --upgrade pip
pip install --upgrade setuptools
pip install -r requirements.txt
pip install -r docs/requirements.txt
pip install -e '.[dev]'

Note that this may take a while to complete.

Running LineaPy

During development, you may want to check how your changes affect the behavior of the package. LineaPy supports several interfaces to run on, and the relevant instructions are documented here. Please select the most convenient option for you.

Note

When running LineaPy, make sure that the virtual environment has been activated.

Development

Making Changes

With development dependencies installed, you are now ready to contribute to the source code! First, make a separate branch for your development work. Please use an informative name so that others can get good sense of what your changes are about.

git checkout -b <NEW-BRANCH-NAME>

After making changes you desire, save them to your development branch:

git add <PATH-TO-CHANGED-FILE>
git commit -m "<COMMIT-MESSAGE>"

Info

To learn more about saving changes in Git, check this tutorial.

Tip

LineaPy provides several pre-commit hooks to automatically standardize styles and formats across its codebase.

To run these hooks automatically upon every new commit:

pre-commit install

To run the hooks even when there are no changes:

pre-commit run --all-files

LineaPy's pre-commit hooks do not run tests since tests are too time-consuming to run on every commit. For testing, see the section below.

Note that these changes have been saved only locally at this point, and you need to "push" them to your forked repo on GitHub:

git push

If the new (development) branch has not been pushed before, you will need to create its counterpart on GitHub with:

git push --set-upstream origin <NEW-BRANCH-NAME>

Documenting Changes

Good code documentation is essential to effective collaboration among different developers. As such, we ask contributors to add proper NumPy-styled docstrings for new functionalities that they add.

Info

Check this guide for updating project documentation.

Testing Changes

Testing is an important part of lineapy's development as it ensures that all features stay functional after changes. Hence, we strongly recommend you add tests for changes you introduce.

Info

Check this guide for adding tests.

To run all tests (beware that this may take a while to complete):

pytest tests

Or, to run select tests (e.g., those that you added/modified):

# Example: Run all tests in a folder
pytest tests/unit/plugins

# Example: Run all tests in a file
pytest tests/unit/plugins/test_writer.py

# Example: Run a particular test
pytest tests/unit/plugins/test_writer.py::test_pipeline_generation

# Example: Run a parametrized test with a particular set of parameter values
pytest tests/unit/plugins/test_writer.py::test_pipeline_generation[script_pipeline_a0_b0]

Integrating Changes

As you make your changes in your development branch, it is very possible that the original lineapy repo is updated by other developers. To ensure that your changes are compatible with these updates by others, you will need to regularly "sync" your development branch with the original lineapy repo. You can do this by first syncing the main branch between your local (forked) repo and the original lineapy repo:

git fetch upstream
git checkout main
git merge upstream/main

Then, sync your development branch with the updated main branch:

git checkout <DEV-BRANCH-NAME>
git rebase main

Note

If updates in the original lineapy repo are not compatible with changes in your development branch, you will need to resolve merge conflict(s). Check this tutorial to learn how.

If the issue persists, please get in touch with LineaPy's core development team on Slack.

Once you are content with your changes and ready to integrate them into the original lineapy project, you can open a pull request following instructions here. Make sure that base repository is set to LineaLabs/lineapy and base to main. To facilitate the review, please provide as much detail as possible about your changes in your pull request.


Was this helpful?

Help us improve docs with your feedback!