---
title: "Contributing"
icon: "lucide/hand-heart"
---
# Contributing to yads

We welcome contributions to `yads`! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated. This guide will walk you through the contribution process.

If anything is unclear after reading this guide, feel free to open a [GitHub issue](https://github.com/texel-sh/yads/issues) and ask for clarification. It's also the place to find tasks that might interest you. If you're not sure where to start, we recommend starting with a smaller issue to get familiar with the codebase architecture.

Once you've picked an issue, comment on it to let others know you're working on it. Use the issue thread to discuss your approach if needed. We're always happy to help you get started.

## Found a bug?

Bug reports help us improve `yads`. Before submitting a bug report:

- Search [existing issues](https://github.com/texel-sh/yads/issues) to avoid duplicates
- Verify the bug exists on the latest version of `yads`
- If you find a similar closed issue, open a new one and reference it

When reporting bugs, include enough detail to help us reproduce the issue. The more information you provide, the faster we can investigate and fix the problem.

## Have a feature idea?

Feature requests are also tracked through [issues](https://github.com/texel-sh/yads/issues). Before suggesting a feature:

- Check if someone has already requested something similar
- Think about how the feature aligns with `yads`' goals—You can read more about it in the [README](README.md). If unclear, suggest the feature anyways! Ideas are always welcome.

In your feature request, explain what you want to achieve and why it would be valuable. Show examples of how you envision using the feature.

## Contributing code

### Environment setup

Contributing to `yads` requires [Python](https://www.python.org/) and [uv](https://github.com/astral-sh/uv) for dependency management.

#### Get the code

You'll need a [GitHub account](https://github.com) and [git](https://git-scm.com) installed. Fork the `yads` repository on GitHub, then clone your fork:

```bash
git clone https://github.com/<your-username>/yads.git
cd yads
```

Add the main repository as a remote to keep your fork up to date:

```bash
git remote add upstream https://github.com/texel-sh/yads.git
git remote -v
```

#### Install dependencies

Install Python 3.10 or newer. We recommend using [uv to manage Python versions](https://docs.astral.sh/uv/concepts/python-versions/).

[Install uv](https://docs.astral.sh/uv/getting-started/installation/) if you haven't already.

Set up your development environment:

```bash
make install
```

This installs all core and development dependencies and sets up pre-commit hooks.

Verify your setup by running tests and linting:

```bash
make test
make lint
```

We use [ruff](https://github.com/astral-sh/ruff) for code formatting and linting.

If everything passes, your development environment is ready. Run `make help` to see all available commands.

#### Keeping dependencies current

Update your environment regularly to avoid conflicts with CI. Sync your fork with the main repository:

```bash
git checkout main
git fetch upstream
git rebase upstream/main
git push origin main
```

Update dependencies:

```bash
make sync
```

### Making changes

Create a new branch from `main` for your work:

```bash
git checkout -b feature/your-feature main
```

The source code lives in `src/yads/`. Use the Makefile commands while developing:

- `make test` - Run the test suite
- `make test-cov` - Run tests with coverage report
- `make lint` - Check formatting and run linters  
- `make format` - Auto-format code
- `make pre-commit` - Run all pre-commit hooks

Your changes won't be merged if tests fail or linting issues exist. Run `make help` to see all available commands.

Remember to:

- Add tests for new functionality
- Update docstrings if you change the public API

### Testing your changes

`yads` has a comprehensive test suite that is organized by module in the `tests/` directory. Write tests that are clear and comprehensive. Use descriptive names that explain what behavior is being verified.

Use the Make targets to run unit tests:
```bash
make test
make test-cov
```

`yads` also tests compatibility with multiple versions of optional dependencies (PySpark, PyArrow, Pydantic, Polars). You can test specific dependency versions locally:

```bash
make test-dependency DEP=pyspark VER=3.5.3
make test-integration DIALECT=spark
```

See the [CI README](https://github.com/texel-sh/yads/blob/main/ci/README.md) for details on dependency testing and integration tests.

### Submitting your work

Open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) when your changes are ready. Follow these guidelines:

**Pull request title:** Use [conventional commit](https://www.conventionalcommits.org/) format with the [Angular convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#type). Start with a type prefix like `feat:`, `fix:`, `docs:`, etc. Write a clear description that makes sense to users reading the changelog. Capitalize the first letter and avoid ending with punctuation. Annotate code references with backticks.

Example: ``fix: Handle null values correctly in nested struct fields``

**Pull request description:** Link to the issue you're addressing. Provide context that helps reviewers understand your changes. Explain any design decisions or trade-offs.

**Before submitting:**

- Rebase your branch on the latest `main`
- Ensure all CI checks pass
- Verify tests and linting pass locally

A maintainer will review your pull request and may suggest changes. Once approved, we'll merge it using "Squash and merge". This keeps the git history clean with one commit per feature.

Don't worry about making everything perfect on the first try. Open a draft pull request if you want feedback on your approach.

## Code conventions

`yads` follows standard Python practices:

- [PEP 8](https://pep8.org/) style guide
- Type hints following [PEP 484](https://www.python.org/dev/peps/pep-0484/)
- Maximum line length of 90 characters
- Modern Python idioms (requires Python 3.10+)
- Google-style docstrings for user-facing code
- Self-documenting names for internal code

Use named imports for the `spec` and `types` modules to prevent name collisions with common terms like Field, String, etc.

Run `make format` before committing to automatically fix formatting issues.

## Development model

`yads` uses trunk-based development. The `main` branch is always stable and ready to deploy. All development happens in short-lived feature branches that get merged via pull requests.

Branch naming suggestions:
- `feature/descriptive-name` for new functionality
- `fix/descriptive-name` for bug fixes

Keep branches focused on a single change. Merge early and often to minimize conflicts. Delete branches after they're merged.

We use "Squash and merge" for all pull requests. This creates a single commit on `main` per feature, keeping history easy to navigate. The PR title becomes the commit message, which is why conventional commit format matters for release notes.

## Documentation

Docs are built with Zensical (from the creators of MkDocs Material) and are configured via the `zensical.toml` file. API reference documentation is automatically parsed by the `mkdocstrings` extension, so every public symbol needs an up-to-date Google-style docstring. Preview the site with:

```bash
uv run --group dev zensical serve
```

Reusable snippets live in `docs/src/examples/` as `EXAMPLE` definitions and you can reference them inside Markdown with `<!-- BEGIN/END:example ... -->` markers:

```markdown
<!-- BEGIN:example example-name code -->
\```python
# example code here
\```
<!-- END:example example-name code -->
<!-- BEGIN:example example-name output -->
\```text
# expected output here
\```
<!-- END:example example-name output -->
```

Keep the examples authoritative and let the sync script rewrite the doc blocks.

It's a good idea to refresh snippets when making changes that may affect public examples. You can use the following make targets for that:

```bash
make sync-examples FILE=docs/converters/pyarrow.md
make sync-examples-all
```

Treat generated example regions as read-only and note the sync command you ran in your PR description.

## Releasing new versions

Maintainers handle releases. The process uses [Release Drafter](https://github.com/release-drafter/release-drafter) to automatically generate release notes from pull request titles. For complete release procedures, see [RELEASE.md](https://github.com/texel-sh/yads/blob/main/.github/RELEASE.md).

Contributors don't need to worry about versions or releases - just focus on your code changes.

## License

Your contributions will be licensed under the same terms as the `yads` project.
