Contributing

Overview

Thanks for showing interest in contributing to pyfixest! We appreciate all contributions and constructive feedback, whether that be reporting bugs, requesting new features, or suggesting improvements to documentation.

If you’d like to get involved, but are not yet sure how, please feel free to send us an email. Some familiarity with either Python or econometrics will help, but you really don’t need to be a numpy core developer or have published in Econometrica =) We’d be more than happy to invest time to help you get started!

Reporting bugs

We use GitHub issues to track bugs. You can report a bug by opening a new issue or contribute to an existing issue if related to the bug you are reporting.

Before creating a bug report, please check that your bug has not already been reported, and that your bug exists on the latest version of pyfixest. If you find a closed issue that seems to report the same bug you’re experiencing, open a new issue and include a link to the original issue in your issue description.

Please include as many details as possible in your bug report. The information helps the maintainers resolve the issue faster.

Suggesting enhancements

We use GitHub issues to track bugs and suggested enhancements. You can suggest an enhancement by opening a new feature request. Before creating an enhancement suggestion, please check that a similar issue does not already exist.

Please describe the behavior you want and why, and provide examples of how pyfixest would be used if your feature were added.

Contributing to the codebase

Setting up your local environment

Would you like to contribute to pyfixest, or run some of the unit tests locally? Awesome! Here’s how you can get started:

First, you’ll want to fork the pyfixest GitHub repository. Then, clone your forked repo with git:

git clone https://github.com/<username>/pyfixest.git
cd pyfixest

To work on pyfixest, you’ll need Python and R installed. If you’re planning to work on the documentation, be sure to have Quarto installed as well. Note: an R installation is only needed if you plan to run the unit tests locally.

For guidance on installing R and Python, check out the sections below.

Package Management via pixi

PyFixest is using pixi.

To install pixi, just follow the installation instructions from the pixi documentation.

Once pixi is installed, you can initialize the project environment and install all dependencies with

cd path-to-pyfixest
pixi install

After installation, you can activate a custom pixi environment for pyfixest by typing:

pixi shell

You’ll now be in the pixi environment and ready to go!

For most development tasks, it’s best to activate the development environment since it includes all the necessary dependencies for development.

pixi shell --environment dev    # open the dev environment

Pixi tasks

To help with development, we’ve included several handy pixi tasks.

For example, we use ruff and pre-commit to ensure code consistency across the project.

To install the required hooks, simply run

pixi run lint

and you’re ready to go! After installation, the task will run all linting rules via ruff.

We’ve included other tasks to help install the necessary R packages for running unit tests or to run different sets of tests:

# install all R development dependencies
pixi run install-r
# run all tests via pytest
pixi run tests
# run all tests excluding very computationally demanding tests
pixi run tests-regular
# rerun failed tests
pixi run tests-rerun

Building the documentation is also straightforward. We’ve got tasks to build, render, and preview the docs:

# Build documentation and website
pixi run docs-build
# render the docs
pixi run docs-render
# preview the docs
pixi run docs-preview

Keep in mind that you’ll need quarto installed to build the documentation locally.

Installing Python, R and Quarto

Installing Python

The minimal Python version to develop pyfixest is 3.9. You can installed it on Mac/Linux via Hombrew:

brew install python@3.11 # specify the version of python you prefer

On Windows via Winget:

winget install -e --id Python.Python.3.11

Installing R

Note that installing R and the R packages listed below is only necessary if you want to test against R in your local installation. You can also test against R by using github actions.

On Mac/Linux:

brew install r

Depending on your local set up, you may need to install additional libraries, for example:

sudo apt install gcc-11 cmake

On Windows using Winget:

winget install -e --id RProject.R

Installing Quarto

Documentation for pyfixest is written, compiled, and published using Quarto.

To install Quarto, run:

On MacOS via Homebrew:

brew install --cask quarto

On Linux (Ubuntu using gdebi):

sudo curl -o quarto-linux-amd64.deb -L <https://github.com/quarto-dev/quarto-cli/releases/download/v${QUARTO_VERSION}/quarto-${QUARTO_VERSION}-linux-amd64.deb>
sudo gdebi quarto-linux-amd64.deb

On Windows:

scoop bucket add extras
scoop install extras/quarto