Make a fork of the main `Dask repository <https://github.com/dask/dask>`_ and
clone the fork::

   git clone https://github.com/<your-github-username>/dask.git
   cd dask

You should also pull the latest git tags (this ensures ``pip``'s dependency resolver
can successfully install Dask)::

   git remote add upstream https://github.com/dask/dask.git
   git pull upstream main --tags

Contributions to Dask can then be made by submitting pull requests on GitHub.

.. _develop-install:

Install
~~~~~~~

From the top level of your cloned Dask repository you can deploy and test a
local version of Dask, along with all necessary dependencies, using
pixi_.

Pixi uses lockfiles to freeze the installed version of all dependencies.
To update the lockfile::

   pixi update

.. _pixi: https://pixi.prefix.dev/


Run Tests
~~~~~~~~~

Dask uses pytest_ for testing. You can run tests from the main dask directory
as follows::

   pixi run test

You can pass arbitrary pytest parameters to the command; e.g.::

   pixi run test dask/tests/test_base.py -k persist

pytest-xdist can be used to run tests in parallel::

   pixi run test -n auto

Test in parallel, with coverage, and including slow tests::

   pixi run test-ci

Generate a local coverage report after running ``test-ci``::

   pixi run coverage html

Run doctests::
   
   pixi run doctest

There are several variant environments for testing, against obsolete but
still supported versions of dependencies, as well as against variant and
experimental configurations::

   pixi run -e mindeps-non-optional test-ci
   pixi run -e mindeps-optional test-ci
   pixi run -e mindeps-array test-ci
   pixi run -e mindeps-dataframe test-ci
   pixi run -e mindeps-distributed test-ci
   pixi run -e py310 test-ci
   pixi run -e py311 test-ci
   pixi run -e py312 test-ci
   pixi run -e py313 test-ci
   pixi run -e py314 test-ci
   pixi run -e py314t test-ci
   pixi run -e nightly test-ci

Note that, besides Python versions, these variant environments also test a
matrix of different versions of NumPy, Pandas, and PyArrow. See ``pixi.toml``
for details.

There are also specialty test tasks::

   pixi run test-spark
   pixi run -e <any environment with NumPy> test-array-expr

.. _pytest: https://docs.pytest.org/en/latest/


Contributing to Code
--------------------

Dask maintains development standards that are similar to most PyData projects. These
standards include language support, testing, documentation, and style.

Python Versions

Dask employs extensive unit tests to ensure correctness of code both for today
and for the future.  Test coverage is expected for all code contributions.

Tests are written in a py.test style with bare functions:

.. code-block:: python

   def test_fibonacci():
       assert fib(0) == 0
       assert fib(1) == 0
       assert fib(10) == 55
       assert fib(8) == fib(7) + fib(6)

       for x in [-3, 'cat', 1.5]:
           with pytest.raises(ValueError):
               fib(x)

These tests should compromise well between covering all branches and fail cases
and running quickly (slow test suites get run less often).

Tests run automatically on GitHub Actions on every push to every pull
request on GitHub.

Tests are organized within the various modules' subdirectories::

    dask/array/tests/test_*.py
    dask/bag/tests/test_*.py
    dask/bytes/tests/test_*.py
    dask/dataframe/tests/test_*.py
    dask/diagnostics/tests/test_*.py

For the Dask collections like Dask Array and Dask DataFrame, behavior is
typically tested directly against the NumPy or pandas libraries using the
``assert_eq`` functions:

.. code-block:: python

   import numpy as np
   import dask.array as da
   from dask.array.utils import assert_eq

   def test_aggregations():
       rng = np.random.default_rng()
       nx = rng.random(100)
       dx = da.from_array(nx, chunks=(10,))

       assert_eq(nx.sum(), dx.sum())
       assert_eq(nx.min(), dx.min())
       assert_eq(nx.max(), dx.max())
       ...

This technique helps to ensure compatibility with upstream libraries and tends
to be simpler than testing correctness directly.  Additionally, by passing Dask
collections directly to the ``assert_eq`` function rather than call compute
manually, the testing suite is able to run a number of checks on the lazy
collections themselves.


Docstrings

   A more thorough description of the function, consisting of multiple
   lines or paragraphs.

   Parameters
   ----------
   i: int
        A short description of the argument if not immediately clear

   Examples
   --------
   >>> fib(4)
   3
   >>> fib(5)
   5
   >>> fib(6)
   8
   >>> fib(-1)  # Robust to bad inputs
   ValueError(...)
   """

Dask uses several code linters (ruff, black, mypy), which are enforced by CI. Developers
should run them locally before they submit a PR, through the single command::

   pixi run lint

This makes sure that linter versions and options are aligned for all developers.

Optionally, you may wish to setup the `pre-commit hooks <https://pre-commit.com/>`_ to
run automatically when you make a git commit. This can be done by running::

   pixi run -e lint pre-commit install

from the root of the Dask repository. Now the code linters will be run each time you
commit changes. You can skip these checks with ``git commit --no-verify`` or with the
short version ``git commit -n``.


Contributing to Documentation
-----------------------------

Dask uses Sphinx_ for documentation, hosted on https://readthedocs.org .
Documentation is maintained in the RestructuredText markup language (``.rst``
files) in ``dask/docs/source``.  The documentation consists both of prose
and API documentation.

The documentation is automatically built, and a live preview is available,
for each pull request submitted to Dask. Additionally, you may also
build the documentation yourself locally by following the instructions outlined
below.

How to build the Dask documentation

Dask uses Github Actions for Continuous Integration (CI) testing for each PR.
These CI builds will run the test suite across a variety of Python versions, operating
systems, and package dependency versions.

The CI workflows for Github Actions are defined in
`.github/workflows <https://github.com/dask/dask/tree/main/.github/workflows>`_
with additional scripts and metadata located in `continuous_integration
<https://github.com/dask/dask/tree/main/continuous_integration>`_.
CI is heavily driven by pixi, which is configured by
`pixi.toml <https://github.com/dask/dask/blob/main/pixi.toml>`_.

Making Pull Requests
--------------------

Pull Request Etiquette

We encourage the use of AI and automated tools to assist in code development,
documentation, and testing. However, we ask that contributors disclose these tools and
use them in a way that aligns with Dask's community guidelines. In particular:

- do not use tools to think or speak for you in discussions, code reviews, or any other 
  interactions within the Dask community.
- Before you open a PR, you (the human) must fully review, understand, and approve
  everything that the AI agent wrote.


.. _Sphinx: https://www.sphinx-doc.org/