Contributing to pytidycensus

Thank you for your interest in contributing to pytidycensus! This document provides guidelines for contributing to the project.

Getting Started

Development Setup

  1. Fork and clone the repository:

    git clone https://github.com/mmann1123/pytidycensus.git
cd pytidycensus

  2. Create a virtual environment:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install in development mode:

    pip install -e ".[dev,docs,test]"

  4. Set up pre-commit hooks (optional but recommended):

    pre-commit install

Running Tests

Run the test suite with:

pytest

For coverage reporting:

pytest --cov=pytidycensus

Building Documentation

Build the documentation locally:

cd docs
sphinx-build -b html . _build/html

Code Style

  • Follow PEP 8 Python style guidelines

  • Use type hints where appropriate

  • Write docstrings for all public functions following Google style

  • Keep line length to 100 characters

Testing

  • Write tests for all new functionality

  • Maintain or improve code coverage

  • Use pytest fixtures for common test data

  • Mock external API calls in tests

Documentation

  • Update docstrings for any changed functions

  • Add examples to docstrings when helpful

  • Update relevant notebook examples if functionality changes

  • Ensure documentation builds without warnings

Submitting Changes

Pull Request Process

  1. Create a feature branch:

    git checkout -b feature/your-feature-name

  2. Make your changes and commit:

    git add .
git commit -m "Add descriptive commit message"

  3. Push to your fork:

    git push origin feature/your-feature-name

  4. Create a pull request on GitHub

Pull Request Guidelines

  • Clear description: Explain what changes you made and why

  • Link issues: Reference any related GitHub issues

  • Test coverage: Ensure tests pass and coverage is maintained

  • Documentation: Update docs if needed

  • Changelog: Add entry to changelog.md for user-facing changes

Types of Contributions

Bug Reports

When reporting bugs, please include:

  • Python version and operating system

  • Minimal code example that reproduces the issue

  • Full error traceback

  • Expected vs. actual behavior

Feature Requests

For new features:

  • Describe the use case and motivation

  • Provide examples of how it would be used

  • Consider backwards compatibility

  • Be open to discussion about implementation

Code Contributions

We welcome:

  • Bug fixes

  • New Census datasets support

  • Performance improvements

  • Documentation improvements

  • Test coverage improvements

  • New examples or tutorials

Census API Guidelines

When working with Census APIs:

  • Respect rate limits and implement appropriate throttling

  • Handle API errors gracefully

  • Cache responses when appropriate

  • Test with both valid and invalid inputs

  • Follow Census Bureau’s terms of service

Example Contributions

We especially welcome:

  • New Jupyter notebook examples

  • Tutorials for specific use cases

  • Real-world data analysis examples

  • Geographic analysis workflows

Questions?

  • Open an issue for questions about contributing

  • Check existing issues and documentation first

  • Be respectful and constructive in discussions

Code of Conduct

This project follows a code of conduct based on the Contributor Covenant. Be respectful, inclusive, and constructive in all interactions.

Recognition

Contributors will be acknowledged in the documentation and release notes. Thank you for helping make pytidycensus better!

Come study with us at The George Washington University

GWU Geography & Environment