Contributing

We welcome contributions to dartfx-dataverse! This guide will help you get started.

Getting Started

Fork the Repository

Fork the repository on GitHub and clone your fork:

git clone https://github.com/YOUR-USERNAME/dataverse-toolkit.git
cd dataverse-toolkit

Set Up Development Environment

Install Hatch (which will use uv if available):

# Install uv first (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Hatch
uv tool install hatch

# Or using pip
pip install hatch

Create and activate a development environment:

hatch shell

Install Pre-commit Hooks (Optional but Recommended)

uv pip install pre-commit
# Or: pip install pre-commit
pre-commit install

Development Workflow

Making Changes

Create a new branch for your feature or fix:

git checkout -b feature/your-feature-name

Make your changes to the code
Write tests for your changes
Run the test suite:
```
hatch run test
```
Check code coverage:
```
hatch run cov
```
Run type checking:
```
hatch run types:check
```
Format and lint your code:
```
ruff format .
ruff check . --fix
```

Code Style

We use Ruff for linting and formatting. The configuration is in pyproject.toml.

Line length: 120 characters
Follow PEP 8 guidelines
Use type hints for all functions
Write descriptive docstrings

Writing Tests

Test Structure

Tests are located in the tests/ directory. We use pytest for testing.

# tests/test_feature.py
import pytest
from dartfx.dataverse import DataverseServer, ServerInstallation

def test_my_feature():
    """Test description."""
    # Arrange
    server = DataverseServer(
        server=ServerInstallation(
            name="Test",
            hostname="test.example.com"
        )
    )

    # Act
    result = server.some_method()

    # Assert
    assert result is not None
    assert isinstance(result, dict)

Running Tests

# Run all tests
hatch run test

# Run specific test file
hatch run test tests/test_search.py

# Run specific test
hatch run test tests/test_search.py::test_search_simple

# Run with coverage
hatch run cov

Documentation

Writing Documentation

Documentation is written in reStructuredText and built with Sphinx.

Documentation source is in docs/source/
Build documentation:
```
hatch run docs:build
```

View documentation locally:

hatch run docs:serve
# Open http://localhost:8000 in your browser

Clean build files:
```
hatch run docs:clean
```

Docstring Format

We use Google-style docstrings:

def search(self, query: str, per_page: int = 10) -> dict:
    """Execute a search query.

    This method searches the Dataverse installation using the
    provided query parameters.

    Args:
        query: The search term or terms to query for
        per_page: Number of results to return per page

    Returns:
        A dictionary containing search results and metadata

    Raises:
        DataverseApiError: If the API request fails

    Example:
        >>> server = DataverseServer(inst)
        >>> results = server.search_simple("climate")
        >>> print(results['data']['total_count'])
    """
    pass

Submitting Changes

Pull Request Process

Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "Add feature: description of your change"

Push to Your Fork

git push origin feature/your-feature-name

Create Pull Request
- Go to the original repository on GitHub
- Click “New Pull Request”
- Select your fork and branch
- Fill out the PR template with:
  - Description of changes
  - Related issues
  - Testing performed
  - Screenshots (if applicable)
Address Review Comments
- Respond to reviewer feedback
- Make requested changes
- Push additional commits to your branch

Pull Request Checklist

Before submitting, ensure:

[ ] Tests pass locally
[ ] Code is formatted with Ruff
[ ] Type checking passes
[ ] Documentation is updated
[ ] Commit messages are clear
[ ] No merge conflicts
[ ] Changes are focused and atomic

Code Review

What We Look For

Correctness: Does the code work as intended?
Tests: Are there tests for new functionality?
Style: Does it follow project conventions?
Documentation: Is it well-documented?
Performance: Are there any performance concerns?
Security: Are there any security issues?

Review Process

Maintainers will review your PR
Feedback will be provided as comments
You may need to make changes
Once approved, maintainers will merge

Reporting Bugs

Bug Report Guidelines

When reporting bugs, please include:

Description: Clear description of the bug
Steps to Reproduce: Minimal steps to reproduce the issue
Expected Behavior: What you expected to happen
Actual Behavior: What actually happened
Environment:
- Python version
- Package version
- Operating system
Code Sample: Minimal code that reproduces the issue

Example Bug Report:

## Bug Description
Search fails when using geo_point parameter

## Steps to Reproduce
```python
from dartfx.dataverse import DataverseServer, SearchParameters

server = DataverseServer(installation)
params = SearchParameters(
    q="*",
    geo_point="42.3,-71.1",
    geo_radius="10"
)
results = server.search(params)  # Fails here
```

## Expected Behavior
Should return search results within 10km radius

## Actual Behavior
Raises DataverseApiError with status 400

## Environment
- Python: 3.12.0
- dartfx-dataverse: 0.2.0
- OS: macOS 14.0

Feature Requests

We welcome feature requests! Please:

Check if the feature already exists or is planned
Describe the use case clearly
Provide examples of how it would work
Explain why it would be valuable

Community Guidelines

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

Be respectful and inclusive
Welcome newcomers
Give constructive feedback
Focus on what’s best for the community

Communication

GitHub Issues: Bug reports and feature requests
GitHub Discussions: General questions and ideas
Pull Requests: Code contributions

Getting Help

If you need help:

Check the documentation
Search existing issues
Ask in GitHub Discussions
Create a new issue with the “question” label

Development Tips

Useful Commands

# Run all tests
hatch run test

# Run tests with coverage
hatch run cov

# Type checking
hatch run types:check

# Format code
ruff format .

# Lint code
ruff check .

# Fix linting issues
ruff check . --fix

# Build documentation
hatch run docs:build

# Serve documentation locally
hatch run docs:serve

Debugging Tests

# Run with verbose output
hatch run test -v

# Run with print statements
hatch run test -s

# Drop into debugger on failure
hatch run test --pdb

Working with Virtual Environments

# Create environment
hatch env create

# Activate shell
hatch shell

# Run command in environment
hatch run python --version

# Remove environment
hatch env remove

Release Process

For Maintainers

Update version in src/dartfx/dataverse/__about__.py
Update CHANGELOG.md
Create a git tag: git tag vX.Y.Z
Push tag: git push origin vX.Y.Z
Create GitHub release
Build and publish to PyPI:
```
hatch build
hatch publish
```

Thank You!

Thank you for contributing to dartfx-dataverse! Your contributions help make this project better for everyone.