Contributing to GeoPandas — GeoPandas 1.2.1.dev0+g199fc53c8.d20260928 documentation

(Contribution guidelines largely copied from pandas)
Contributions to GeoPandas are very welcome. They are likely to be accepted more quickly if they follow these guidelines.
At this stage of GeoPandas development, the priorities are to define a simple, usable, and stable API and to have clean, maintainable, readable code. Performance matters, but not at the expense of those goals.
In general, GeoPandas follows the conventions of the pandas project where applicable.
In particular, when submitting a pull request:
All existing tests should pass. Please make sure that the test suite passes, both locally and on GitHub Actions. Status on GHA will be visible on a pull request. GHA are automatically enabled on your own fork as well. To trigger a check, make a PR to your own fork.
New functionality should include tests. Please write reasonable tests for your code and make sure that they pass on your pull request.
Classes, methods, functions, etc. should have docstrings. The first line of a docstring should be a standalone summary. Parameters and return values should be documented explicitly.
Follow PEP 8 when possible. We use ruff to ensure a consistent code format throughout the project. For more details see the section Style Guide below.
Imports should be grouped with standard library imports first, 3rd-party libraries next, and GeoPandas imports third. Within each grouping, imports should be alphabetized. Always use absolute imports when possible, and explicit relative imports for local imports when necessary in tests.
GeoPandas supports Python 3.10+ only.
Unless your PR implements minor changes or internal work only, make sure it contains a note describing the changes in the CHANGELOG.md file.
There are seven basic steps to contributing to GeoPandas:
Fork the GeoPandas git repository
Create a development environment
Install GeoPandas dependencies
Make a development build of GeoPandas
Make changes to code and add tests
Update the documentation
Submit a Pull Request
Each of these 7 steps is detailed below.
To the new user, working with Git is one of the more daunting aspects of contributing to GeoPandas. It can very quickly become overwhelming, but sticking to the guidelines below will help keep the process straightforward and mostly trouble free. As always, if you are having difficulties please feel free to ask for help.
The code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on the project.
Some great resources for learning Git:
Software Carpentry’s Git Tutorial
the GitHub help pages.
Matthew Brett’s Pydagogue.
GitHub has instructions 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.
You will need your own fork to work on the code. Go to the GeoPandas project page and hit the Fork button. You will want to clone your fork to your machine:
This creates the directory geopandas-yourname and connects your repository to the upstream (main project) GeoPandas repository.
The testing suite will run automatically on GitHub Actions once your pull request is submitted. The test suite will also automatically run on your branch so you can check it prior to submitting the pull request.
You want your main branch to reflect only production-ready code, so create a feature branch for making your changes. For example:
The above can be simplified to:
This changes your working directory 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 GeoPandas. You can have many shiny-new-features and switch in between them using the git checkout command.
To update this branch, you need to retrieve the changes from the main branch:
This will replay your commits on top of the latest GeoPandas git main. If this leads to merge conflicts, you must resolve these before submitting your pull request. If you have uncommitted changes, you will need to stash them prior to updating. This will effectively store your changes and they can be reapplied after updating.
A development environment is a virtual space where you can keep an independent installation of GeoPandas. This makes it easy to keep both a stable version of python in one place you use for work, and a development version (which you may break while playing with code) in another.
An easy way to create a GeoPandas development environment is as follows:
Install either Anaconda or miniconda
Make sure that you have cloned the repository