contributing.qmd

---
title: Contributing
toc: true
toc-title: "On this page"
toc-location: left
---

## 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](alexander-fischer1801@t-online.de). 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](https://onlinelibrary.wiley.com/journal/14680262) =) We'd be more than happy to invest time to help you get started!

## Reporting bugs

We use [GitHub issues](https://github.com/py-econometrics/pyfixest/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](https://github.com/py-econometrics/pyfixest/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement) 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:

```{.bash .code-copy}
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](https://pixi.sh/latest/).

To install `pixi`, just follow the [installation instructions](https://pixi.sh/latest/#installation) from the `pixi` documentation.

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

```{.bash .code-copy}
cd path-to-pyfixest
pixi install
```

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

```{.bash .code-copy}
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.

```{.bash .code-copy}
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

```{.bash .code-copy}
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:
```{.bash .code-copy}
# 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:

```{.bash .code-copy}
# 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](https://brew.sh/):

```{.bash .code-copy}
brew install python@3.11 # specify the version of python you prefer
```

On Windows via [Winget](https://winget.run/pkg/Python/Python.3.11):
```{.bash .code-copy}
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:
```{.bash .code-copy}
brew install r
```

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

```{.bash .code-copy}
sudo apt install gcc-11 cmake
```

On Windows using [Winget](https://winget.run/pkg/RProject/R):

```{.bash .code-copy}
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](https://formulae.brew.sh/cask/quarto#default):

```{.bash .code-copy}
brew install --cask quarto
```

On Linux (Ubuntu using `gdebi`):

```{.bash .code-copy}
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:

```{.bash .code-copy}
scoop bucket add extras
scoop install extras/quarto
```