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 an issue and ask for clarification.

Found a bug?¶

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

Search existing 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?¶

We track feature requests through GitHub 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. If unclear, suggest the feature anyways! We love hearing new ideas.

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¶

Finding something to work on¶

Browse the issue tracker to find tasks that interest you. Look for issues that aren't assigned to anyone. The yads codebase covers schema specification, type systems, and converters for multiple frameworks, so there's plenty of variety.

Start with smaller issues 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.

Environment setup¶

Contributing to yads requires Python and uv for dependency management.

Get the code¶

You'll need a GitHub account and git installed. Fork the yads repository on GitHub, then clone your fork:

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

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

git remote add upstream https://github.com/erich-hs/yads.git
git fetch upstream

Install dependencies¶

Install Python 3.10 or newer. We recommend using uv to manage Python versions.

Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Set up your development environment:

make install

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

Verify your setup by running tests and linting:

make test
make lint

We use 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:

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

Update dependencies:

make sync

Making changes¶

Create a new branch from main for your work:

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:

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:

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

See the CI README for details on dependency testing and integration tests.

Submitting your work¶

Open a pull request when your changes are ready. Follow these guidelines:

Pull request title: Use conventional commit format with the Angular convention. 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 style guide
Type hints following PEP 484
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:

uv run --group dev zensical serve

Reusable snippets live in docs/src/examples/ as EXAMPLE definitions and you can reference them inside Markdown with  markers:

<!-- 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:

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 to automatically generate release notes from pull request titles. For complete release procedures, see 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.