Contributing

Thank you for considering contributing to the USDA FDC Python Client! This document provides guidelines and instructions for contributing to the project.

Setting Up Development Environment

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/mcgarrah/usda_fdc_python
cd usda_fdc_python

Install development dependencies:
```
pip install -e ".[dev]"
```
Set up pre-commit hooks:
```
pre-commit install
```

Code Style

This project uses:

Black for code formatting
isort for import sorting
flake8 for linting
mypy for type checking

You can run these tools manually:

# Format code
black usda_fdc tests

# Sort imports
isort usda_fdc tests

# Lint code
flake8 usda_fdc tests

# Type check
mypy usda_fdc

Or use pre-commit to run them automatically:

pre-commit run --all-files

Testing

Please write tests for new features and bug fixes. This project uses pytest:

# Run all tests
pytest

# Run tests with coverage
pytest --cov=usda_fdc

For more details on testing, see Testing.

Running Specific Test Categories

The test suite is organized into three categories:

# Run unit tests only (default)
pytest tests/unit

# Run integration tests (requires API key)
pytest -m integration

# Run Django tests (requires Django)
pytest -m django

For integration tests, you’ll need to set your API key:

export FDC_API_KEY=your_api_key_here

Documentation

Please update documentation for any changes:

Update docstrings for any modified functions or classes.
Update or add RST files in the docs/ directory as needed.

Build and check the documentation locally:

cd docs
make html
# Open _build/html/index.html in your browser

Pull Request Process

Create a new branch for your feature or bugfix:
```
git checkout -b feature-or-bugfix-name
```
Make your changes and commit them with clear, descriptive commit messages.
Ensure all tests pass:
```
pytest
```
Push your branch to your fork:
```
git push origin feature-or-bugfix-name
```
Submit a pull request to the main repository.
Ensure the CI checks pass.
Address any feedback from maintainers.

Code of Conduct

Please be respectful and considerate of others when contributing to this project. We aim to foster an inclusive and welcoming community.