Skip to content

Latest commit

 

History

History
188 lines (131 loc) · 8.71 KB

CONTRIBUTING.md

File metadata and controls

188 lines (131 loc) · 8.71 KB
Raw

Contributing

Thank you for your interest in contributing to Narwhals! Any kind of improvement is welcome!

Local development vs Codespaces

You can contribute to Narwhals in your local development environment, using python3, git and your editor of choice. You can also contribute to Narwhals using Github Codespaces - a development environment that's hosted in the cloud. This way you can easily start to work from your browser without installing git and cloning the repo. Scroll down for instructions on how to use Codespaces.

Working with local development environment

1. Make sure you have git on your machine and a GitHub account

Open your terminal and run the following command:

git --version

If the output looks like git version 2.34.1 and you have a personal account on GitHub - you're good to go to the next step. If the terminal output informs about command not found you need to install git.

If you're new to GitHub, you'll need to create an account on GitHub.com and verify your email address.

2. Fork the repository

Go to the main project page. Fork the repository by clicking on the fork button. You can find it in the right corner on the top of the page.

3. Clone the repository

Go to the forked repository on your GitHub account - you'll find it on your account in the tab Repositories. Click on the green Code button and then click the Copy url to clipboard icon. Open a terminal, choose the directory where you would like to have Narwhals repository and run the following git command:

git clone <url you just copied>

for example:

git clone [email protected]:YOUR-USERNAME/narwhals.git

4. Setting up your environment

Here's how you can set up your local development environment to contribute.

Option 1: Use UV (recommended)

  1. Make sure you have Python3.8+ installed (for example, Python 3.11), create a virtual environment, and activate it. If you're new to this, here's one way that we recommend:
    1. Install uv: https://github.com/astral-sh/uv?tab=readme-ov-file#getting-started
    2. Install some version of Python greater than Python3.8. For example, to install Python3.11: 
      uv python install 3.11
    3. Create a virtual environment: 
      uv venv -p 3.11 --seed
    4. Activate it. On Linux, this is . .venv/bin/activate, on Windows .\.venv\Scripts\activate.
  2. Install Narwhals: uv pip install -e .
  3. Install test requirements: uv pip install -r requirements-dev.txt
  4. Install docs requirements: uv pip install -r docs/requirements-docs.txt

You should also install pre-commit:

uv pip install pre-commit
pre-commit install

This will automatically format and lint your code before each commit, and it will block the commit if any issues are found.

Option 2: use python3-venv

  1. Make sure you have Python 3.8+ installed. If you don't, you can check install Python to learn how. Then, create and activate a virtual environment.
  2. Then, follow steps 2-4 from above but using pip install instead of uv pip install.

5. Working on your issue

Create a new git branch from the main branch in your local repository. Note that your work cannot be merged if the test below fail. If you add code that should be tested, please add tests.

6. Running tests

  • To run tests, run pytest. To check coverage: pytest --cov=narwhals
  • To run tests on the doctests, use pytest narwhals --doctest-modules
  • To run unit tests and doctests at the same time, run pytest tests narwhals --cov=narwhals --doctest-modules
  • To run tests multiprocessed, you may also want to use pytest-xdist (optional)

If you want to have less surprises when opening a PR, you can take advantage of nox to run the entire CI/CD test suite locally in your operating system.

To do so, you will first need to install nox and then run the nox command in the root of the repository:

python -m pip install nox  # python -m pip install "nox[uv]"
nox

Notice that nox will also require to have all the python versions that are defined in the noxfile.py installed in your system.

7. Building docs

To build the docs, run mkdocs serve, and then open the link provided in a browser. The docs should refresh when you make changes. If they don't, press ctrl+C, and then do mkdocs build and then mkdocs serve.

8. Pull requests

When you have resolved your issue, open a pull request in the Narwhals repository.

Please adhere to the following guidelines:

  1. Start your pull request title with a conventional commit tag. This helps us add your contribution to the right section of the changelog. We use "Type" from the Angular convention.
    TLDR: The PR title should start with any of these abbreviations: build, chore, ci, depr, docs, feat, fix, perf, refactor, release, test. Add a !at the end, if it is a breaking change. For example refactor!.
  2. This text will end up in the changelog.
  3. Please follow the instructions in the pull request form and submit.

Working with Codespaces

Codespaces is a great way to work on Narwhals without the need of configuring your local development environment. Every GitHub.com user has a monthly quota of free use of GitHub Codespaces, and you can start working in a codespace without providing any payment details. You'll be informed per email if you'll be close to using 100% of included services. To learn more about it visit GitHub Docs

1. Make sure you have GitHub account

If you're new to GitHub, you'll need to create an account on GitHub.com and verify your email address.

2. Fork the repository

Go to the main project page. Fork the repository by clicking on the fork button. You can find it in the right corner on the top of the page.

3. Create codespace

Go to the forked repository on your GitHub account - you'll find it on your account in the tab Repositories. Click on the green Code button and navigate to the Codespaces tab. Click on the green button Create codespace on main - it will open a browser version of VSCode, with the complete repository and git installed. You can now proceed with the steps 4. Setting up your environment up to 8. Pull request listed above in Working with local development environment.

How it works

If Narwhals looks like underwater unicorn magic to you, then please read how it works.

Imports

In Narwhals, we are very particular about imports. When it comes to importing heavy third-party libraries (pandas, NumPy, Polars, etc...) please follow these rules:

  • Never import anything to do isinstance checks. Instead, just use the functions in narwhals.dependencies (such as is_pandas_dataframe);
  • If you need to import anything, do it in a place where you know that the import is definitely available. For example, NumPy is a required dependency of PyArrow, so it's OK to import NumPy to implement a PyArrow function - however, NumPy should never be imported to implement a Polars function. The only exception is for when there's simply no way around it by definition - for example, Series.to_numpy always requires NumPy to be installed.
  • Don't place a third-party import at the top of a file. Instead, place it in the function where it's used, so that we minimise the chances of it being imported unnecessarily.

We're trying to be really lightweight and minimal-overhead, and unnecessary imports can slow things down.

Happy contributing!

Please remember to abide by the code of conduct, else you'll be conducted away from this project.

Community Calendar

We have a community call every 2 weeks, all welcome to attend.

Subscribe to our calendar.