Contributing

Contributing#

Thank you for your interest in contributing to FOLIO Data Import! This document explains how to get involved.

Code of Conduct#

We are committed to providing a welcoming and inspiring community for all. Please read and follow our Code of Conduct.

How Can I Contribute?#

Reporting Bugs#

Found a bug? Please report it on our GitHub Issue tracker.

When reporting a bug, please include:

  • Description - What happened vs. what you expected

  • Steps to reproduce - Clear steps to recreate the issue

  • Logs - Error messages and relevant logs (sanitized for sensitive data)

  • Environment - Python version, OS, FOLIO version

  • Data sample - Small sample data that demonstrates the issue (if applicable)

Suggesting Enhancements#

Have an idea for improvement? Open an issue with:

  • Description - What feature you’d like and why

  • Use case - Why this would be useful

  • Alternatives - Any alternative approaches you’ve considered

  • Example - Code example showing how it would be used

Pull Requests#

We welcome pull requests for bug fixes and features. To contribute code:

  1. Fork the repository

  2. Create a branch for your feature: git checkout -b feature/my-feature

  3. Make your changes

  4. Add tests if applicable

  5. Update documentation

  6. Commit with clear messages: git commit -m "Add feature description"

  7. Push to your fork

  8. Create a pull request with a clear description

Development Setup#

Prerequisites#

  • Python 3.10 or higher

  • Git

  • uv (recommended) or pip

Installation#

  1. Clone the repository:

git clone https://github.com/FOLIO-FSE/folio_data_import.git
cd folio_data_import

  1. Install dependencies with uv:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install all dependencies (creates .venv automatically)
uv sync

Code Standards#

Style#

We follow PEP 8 with some modifications:

  • Line length: 99 characters

  • Use double quotes for strings

  • Use type hints where practical

We use Ruff for both formatting and linting:

# Format code
uv run ruff format src/ tests/

# Lint code and auto-fix where possible
uv run ruff check src/ tests/ --fix

Documentation#

All public functions and classes should have docstrings:

def post_records(self, batch_size: int = 250) -> dict:
    """Post all records to FOLIO.
    
    Args:
        batch_size: Number of records per API request.
        
    Returns:
        Dictionary with keys 'success', 'failed', 'errors'.
        
    Raises:
        BatchPosterException: If posting fails.
    """

Testing#

Write tests for new features and bug fixes.

Running Tests#

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=folio_data_import

# Run specific test file
uv run pytest tests/test_batch_poster.py

# Run with verbose output
uv run pytest -v

Writing Tests#

Create test files in the tests/ directory:

import pytest
from folio_data_import import BatchPoster

def test_batch_poster_initialization():
    """Test BatchPoster initialization."""
    poster = BatchPoster(
        okapi_url="https://example.com",
        tenant_id="test",
        username="admin",
        password="secret",
        record_file="test.json",
        object_type="Instances"
    )
    assert poster.okapi_url == "https://example.com"

Documentation#

Building Documentation#

Build the documentation locally:

uv sync --group docs
cd docs
uv run sphinx-build -b html -d _build/doctrees -c . source _build/html

Open _build/html/index.html in your browser.

Writing Documentation#

Documentation files go in docs/source/ as Markdown:

  • Use clear, accessible language

  • Include code examples

  • Link to related sections

  • Keep paragraphs short

Pull Request Process#

  1. Update documentation and tests

  2. Ensure all tests pass: uv run pytest

  3. Format and lint: uv run ruff format . && uv run ruff check . --fix

  4. Build documentation locally: cd docs && uv run sphinx-build -b html -d _build/doctrees -c . source _build/html

  5. Create a detailed pull request with:

    • Clear description of changes

    • Reference to any related issues

    • Screenshots if UI changes

    • Any breaking changes clearly noted

Commit Messages#

Write clear, descriptive commit messages:

Add feature: Brief description

Longer description of what was changed and why,
spanning multiple lines if needed.

Fixes #123

Questions?#

Have questions about contributing? Feel free to:

  • Open an issue with your question

  • Check existing issues and discussions

  • Contact a maintainer

Code Ownership#

When you contribute code to this project, you agree that:

  • Your code can be used under the project’s license (MIT)

  • You have the right to contribute the code

  • Your contributions are original

Thank you for helping improve FOLIO Data Import!

Contents