.. _contributing:

{{ header }}

**********************
Contributing to pandas
**********************

.. contents:: Table of contents:
   :local:


All contributions, bug reports, bug fixes, documentation improvements,
enhancements, and ideas are welcome. We ask that contributors follow
all contribution guidelines when participating with pandas.

.. _contributing.ai:

Automated contributions policy
==============================

Contributors may use automated tools such as AI coding assistants while contributing
to pandas as long as it's used **responsibly**. Any use of these tools in a contribution must abide by all of the
following guidelines:

* You must disclose that you used an automated tool in the contribution, and be specific about which one.
* You must fully review and modify the result of the automated tool.
* You must ensure the contribution fully abides by all documented, contribution conventions in pandas.
* You must not use AI to speak for you when interacting with the community.

A useful disclosure names the tool, the model and version it ran, and any reasoning-effort or thinking setting, so
that reviewers know how much scrutiny to apply: ``claude opus 4.8 (xhigh)`` tells us something, ``claude`` does not.
Not every tool exposes an effort setting, so give what applies. If you used more than one tool or model, say which
parts of the contribution each was responsible for.

Using these tools to help write the code, tests, and documentation in a contribution is fine. Discussion is
different: in issues, pull requests, and review comments, do not use AI to speak for you. Copying and pasting
AI-written replies does not count as engaging with a reviewer, and human-to-human communication is essential for
the project to thrive.

Translation and grammar editing are an explicit exception to the rule above. If English is not your first language,
you are welcome to use these tools to help you say what you mean. What we ask is that the thoughts are yours, not
that the English is unaided. Disclosure still applies, so say that you used a tool.

If you need to quote the output of an AI tool as evidence, for example a traceback or a suggested diff, mark it
clearly by quoting it with ``>`` or wrapping it in a triple-backtick code fence, so readers can tell which parts
are your own words.

This policy applies to any contribution made to pandas, including submitted issues or pull requests. Maintainers
reserve the right to discern whether automated tooling was used and reject contributions that do not follow all of
the above guidelines. Maintainers may also ban users from contributing to pandas who violate these guidelines 2 or more times.

.. _contributing.bug_reports:

Bug reports and enhancement requests
====================================

Bug reports and enhancement requests are an important part of making pandas more stable and
are curated through Github issues. When reporting an issue or request, please select the `appropriate
category and fill out the issue form fully <https://github.com/pandas-dev/pandas/issues/new/choose>`_
to ensure others and the core development team can fully understand the scope of the issue.

The issue will then show up to the pandas community and be open to comments/ideas from others.

Finding an issue to contribute to
=================================

If you are brand new to pandas or open-source development, we recommend searching
the `GitHub "issues" tab <https://github.com/pandas-dev/pandas/issues>`_
to find issues that interest you and are available to work on. Issues available to work on are:

* Issues without the label ``Needs Triage`` or ``Needs Discussion``. These issues require clarification and confirmation
  from a maintainer before proceeding.
* Issues that are not already assigned to another contributor.

Once you've found an interesting, available issue, claim it by commenting ``/take``
on the issue and it will be assigned to you. See
:ref:`contributing.issue_assignment` for the full set of rules around claiming
and releasing issues, and how pull requests progress once opened.

For advice on choosing an issue that is a good fit for you, see Marco Gorelli's
`Don't start with good first issues
<https://labs.quansight.org/blog/dont-start-with-good-first-issues>`_.

Contributions are also welcome at `pandas-stubs
<https://github.com/pandas-dev/pandas-stubs/issues>`_, the officially supported
type stubs for pandas. It is maintained as a separate project, so the issue
assignment and pull request rules described in this guide do not apply there —
check its contributing guidelines before starting.

We have several :ref:`contributor community <community>` communication channels, which you are
welcome to join, and ask questions as you figure things out. Among them are regular meetings for
new contributors, dev meetings, a dev mailing list, and a Slack for the contributor community.
All pandas contributors are welcome to these spaces, where they can connect with each other. Even
maintainers who have been with us for a long time felt just like you when they started out, and
are happy to welcome you and support you as you get to know how we work, and where things are.
Take a look at the next sections to learn more.

.. _contributing.issue_assignment:

Issue assignment and the pull request lifecycle
===============================================

To keep contributing fair and avoid duplicated effort, pandas automates how
issues are claimed and how pull requests progress. This section explains the
rules and what the automation does.

Claiming an issue
-----------------

Before opening a pull request, claim the issue by commenting ``/take`` on it.
The bot will assign the issue to you.

An issue is available to claim if it is:

* **not** labeled ``Needs Triage`` or ``Needs Discussion`` — these still need a
  maintainer's review before work begins, and ``/take`` will be declined; and
* **not** already assigned to someone else.

If you change your mind, comment ``/untake`` to release the issue so others can
pick it up.

Opening a pull request
----------------------

Link your pull request to the issue it resolves using a closing keyword in the
description, for example ``closes #1234``.

Your pull request must be linked to an issue that is **assigned to you**. If you
open one linked to an issue you haven't claimed, the bot adds the
``Needs Issue Assignment`` label, closes the pull request, and comments with
what to do next: comment ``/take`` on the issue to claim it, then reopen your
pull request (you can reopen it yourself — nothing is lost).

Review and staleness
--------------------

The purpose of this process is only to identify and clean up abandoned pull
requests — it is never meant to pressure you while you wait: a pull request
goes stale only through its author's own inactivity, never through time spent
waiting on review.

While your pull request is waiting on review it is labeled ``Awaiting Review``
and will **not** be marked stale — you keep your assignment for as long as review
takes.

Once a maintainer requests changes, a **14-day** timer starts. Only *your*
activity resets it: pushing a commit, replying to a
review comment, or commenting on the pull request **or its linked issue** (a
comment from someone else does not).
If there is no activity from you for 14 days, the pull request is marked
``Stale``; your next push or comment clears the label and resets the timer. If it
stays stale for another **7 days**, it is automatically closed — you can reopen
it yourself at any time to continue, and nothing is lost. When a stale pull
request is closed, its linked issue is automatically unassigned and becomes
available again.

When you've addressed the feedback and want another look, **re-request a review**
(the ↻ button next to the reviewer). That moves the pull request back to
``Awaiting Review`` and stops the staleness timer; pushing commits alone does not
return it to the review queue. The timer also stops when the maintainer who
requested changes approves your pull request.

.. note::

   Label changes and unassignment run on a once-a-day job, so they may take up
   to a day to appear. Your activity counts from when you make it.

These rules cover external contributions — pull requests from pandas maintainers
are exempt from the staleness lifecycle.

Inactive assignments
--------------------

If you claim an issue but do not open a linked pull request or stay active on it
for **7 days**, the issue is automatically unassigned and made available again.
You're welcome to ``/take`` it again whenever you're ready.

.. _contributing.github:

Submitting a pull request
=========================

.. _contributing.version_control:

Version control, Git, and GitHub
--------------------------------

pandas is hosted on `GitHub <https://www.github.com/pandas-dev/pandas>`_, and to
contribute, you will need to sign up for a `free GitHub account
<https://github.com/signup/free>`_. We use `Git <https://git-scm.com/>`_ for
version control to allow many people to work together on the project.

If you are new to Git, you can reference some of these resources for learning Git. Feel free to reach out
to the :ref:`contributor community <community>` for help if needed:

* `Git documentation <https://git-scm.com/doc>`_.

Also, the project follows a forking workflow further described on this page whereby
contributors fork the repository, make changes and then create a pull request.
So please be sure to read and follow all the instructions in this guide.

If you are new to contributing to projects through forking on GitHub,
take a look at the `GitHub documentation for contributing to projects <https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_.
GitHub provides a quick tutorial using a test repository that may help you become more familiar
with forking a repository, cloning a fork, creating a feature branch, pushing changes and
making pull requests.

Below are some useful resources for learning more about forking and pull requests on GitHub:

* the `GitHub documentation for forking a repo <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_.
* the `GitHub documentation for collaborating with pull requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests>`_.
* the `GitHub documentation for working with forks <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks>`_.

Getting started with Git
------------------------

`GitHub has instructions <https://docs.github.com/en/get-started/quickstart/set-up-git>`__ for installing git,
setting up your SSH key, and configuring git.  All these steps need to be completed before
you can work seamlessly between your local repository and GitHub.

.. _contributing.forking:

Create a fork of pandas
-----------------------

You will need your own copy of pandas (aka fork) to work on the code. Go to the `pandas project
page <https://github.com/pandas-dev/pandas>`_ and hit the ``Fork`` button. Please uncheck the box to copy only the main branch before selecting ``Create Fork``.
You will want to clone your fork to your machine

.. code-block:: shell

    git clone https://github.com/your-user-name/pandas.git pandas-yourname
    cd pandas-yourname
    git remote add upstream https://github.com/pandas-dev/pandas.git
    git fetch upstream --tags

This creates the directory ``pandas-yourname`` and connects your repository to
the upstream (main project) *pandas* repository.

.. note::

    Performing a shallow clone (with ``--depth==N``, for some ``N`` greater
    or equal to 1) might break some tests and features as ``pd.show_versions()``
    as the version number cannot be computed anymore.

Creating a feature branch
-------------------------

Your local ``main`` branch should always reflect the current state of pandas repository.
First ensure it's up-to-date with the main pandas repository.

.. code-block:: shell

    git checkout main
    git pull upstream main --ff-only

Then, create a feature branch for making your changes. For example

.. code-block:: shell

    git checkout -b shiny-new-feature

This changes your working branch from ``main`` to the ``shiny-new-feature`` branch.  Keep any
changes in this branch specific to one bug or feature so it is clear
what the branch brings to pandas. You can have many feature branches
and switch in between them using the ``git checkout`` command.

When you want to update the feature branch with changes in main after
you created the branch, check the section on
:ref:`updating a PR <contributing.update-pr>`.

.. _contributing.commit-code:

Making code changes
-------------------

Before modifying any code, ensure you follow the :ref:`contributing environment <contributing_environment>`
guidelines to set up an appropriate development environment.

Then once you have made code changes, you can see all the changes you've currently made by running.

.. code-block:: shell

    git status

For files you intended to modify or add, run.

.. code-block:: shell

    git add path/to/file-to-be-added-or-changed.py

Running ``git status`` again should display

.. code-block:: shell

    On branch shiny-new-feature

         modified:   /relative/path/to/file-to-be-added-or-changed.py


Finally, commit your changes to your local repository with an explanatory commit
message

.. code-block:: shell

    git commit -m "your commit message goes here"

.. _contributing.push-code:

Pushing your changes
--------------------

When you want your changes to appear publicly on your GitHub page, push your
forked feature branch's commits

.. code-block:: shell

    git push origin shiny-new-feature

Here ``origin`` is the default name given to your remote repository on GitHub.
You can see the remote repositories

.. code-block:: shell

    git remote -v

If you added the upstream repository as described above you will see something
like

.. code-block:: shell

    origin  git@github.com:yourname/pandas.git (fetch)
    origin  git@github.com:yourname/pandas.git (push)
    upstream        git://github.com/pandas-dev/pandas.git (fetch)
    upstream        git://github.com/pandas-dev/pandas.git (push)

Now your code is on GitHub, but it is not yet a part of the pandas project. For that to
happen, a pull request needs to be submitted on GitHub.

Making a pull request
---------------------

Once you have finished your code changes, your code change will need to follow the
:ref:`pandas contribution guidelines <contributing_codebase>` to be successfully accepted.

If everything looks good, you are ready to make a pull request. A pull request is how
code from your local repository becomes available to the GitHub community to review
and merged into the project to appear in the next release. To submit a pull request:

#. Navigate to your repository on GitHub
#. Click on the ``Compare & pull request`` button
#. You can then click on ``Commits`` and ``Files Changed`` to make sure everything looks
   okay one last time
#. Write a descriptive title that includes prefixes. pandas uses a convention for title
   prefixes. Here are some common ones along with general guidelines for when to use them:

   * ENH: Enhancement, new functionality
   * BUG: Bug fix
   * DOC: Additions/updates to documentation
   * TST: Additions/updates to tests
   * BLD: Updates to the build process/scripts
   * PERF: Performance improvement
   * TYP: Type annotations
   * CLN: Code cleanup

#. Complete the checklist template in the body of the pull request and write an additional description below the checklist if necessary.
#. Click ``Send Pull Request``.

This request then goes to the repository maintainers, and they will review
the code.

.. note::
    A pull request should be associated with an open Github issue except if the change is trivial such as fixing a typo.
    Pull requests that do not abide by all the applicable contribution guidelines may be closed by a maintainer. Contributors
    who have shown continued, quality pull requests may be exempt from following all guidelines strictly.

.. warning::
    pandas will not accept low quality pull requests that do not meaningfully contribute to the project. Maintainers reserve
    their right to close these pull requests and ban users who repeatedly submit low quality pull requests.

.. _contributing.update-pr:

Updating your pull request
--------------------------

Based on the review you get on your pull request, you will probably need to make
some changes to the code. You can follow the :ref:`code committing steps <contributing.commit-code>`
again to address any feedback and update your pull request.

It is also important that updates in the pandas ``main`` branch are reflected in your pull request.
To update your feature branch with changes in the pandas ``main`` branch, run:

.. code-block:: shell

    git checkout shiny-new-feature
    git fetch upstream
    git merge upstream/main

If there are no conflicts (or they could be fixed automatically), a file with a
default commit message will open, and you can simply save and quit this file.

If there are merge conflicts, you need to solve those conflicts. See for
example at https://help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/
for an explanation on how to do this.

Once the conflicts are resolved, run:

#. ``git add -u`` to stage any files you've updated;
#. ``git commit`` to finish the merge.

.. note::

    If you have uncommitted changes at the moment you want to update the branch with
    ``main``, you will need to ``stash`` them prior to updating (see the
    `stash docs <https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning>`__).
    This will effectively store your changes and they can be reapplied after updating.

After the feature branch has been updated locally, you can now update your pull
request by pushing to the branch on GitHub:

.. code-block:: shell

    git push origin shiny-new-feature

Any ``git push`` will automatically update your pull request with your branch's changes
and restart the :ref:`Continuous Integration <contributing.ci>` checks.

.. _contributing.update-dev:

Updating the development environment
------------------------------------

It is important to periodically update your local ``main`` branch with updates from the pandas ``main``
branch and update your development environment to reflect any changes to the various packages that
are used during development.

If using :ref:`conda <contributing.conda>`, run:

.. code-block:: shell

    git checkout main
    git fetch upstream
    git merge upstream/main
    conda activate pandas-dev
    conda env update -f environment.yml --prune

If using :ref:`pip <contributing.pip>` , do:

.. code-block:: shell

    git checkout main
    git fetch upstream
    git merge upstream/main
    # activate the virtual environment based on your platform
    python -m pip install --upgrade -r requirements-dev.txt

Tips for a successful pull request
==================================

If you have made it to the `Making a pull request`_ phase, one of the core contributors may
take a look. Please note however that a handful of people are responsible for reviewing
all of the contributions, which can often lead to bottlenecks.

To improve the chances of your pull request being reviewed, you should:

- **Reference an open issue** for non-trivial changes to clarify the PR's purpose
- **Ensure you have appropriate tests**. These should be the first part of any PR
- **Keep your pull requests as simple as possible**. Larger PRs take longer to review
- **Ensure that CI is in a green state**. Reviewers may not even look otherwise
- **Keep** `Updating your pull request`_, either by request or every few days
