Skip to main content

Contributing

Thank you for your interest in contributing to undatum! This document provides guidelines and instructions for contributing.

Development Setup​

Prerequisites​

  • Python 3.9 or higher
  • Git
  • pip

Installation​

  1. Clone the repository:
git clone https://github.com/datenoio/undatum.git
cd undatum
  1. Create a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install development dependencies:
make install-dev
# or
pip install -e ".[dev]"

Or install manually:

pip install -e .
pip install black ruff mypy pylint pytest pytest-cov pre-commit

Code Style​

Formatting​

We use black for code formatting with a line length of 100 characters:

black undatum/

Linting​

We use ruff for fast linting and pylint for deeper analysis:

ruff check undatum/
pylint undatum/

Type Checking​

We use mypy for type checking:

mypy undatum/

Pre-commit Hooks​

Install pre-commit hooks to automatically check code before commits:

pre-commit install

Documentation​

Docstring Style​

We use Google-style docstrings for consistency. Example:

def example_function(param1: str, param2: int = 10) -> bool:
    """Brief description of the function.

    Longer description explaining what the function does, any important
    details about its behavior, and any relevant context.

    Args:
        param1: Description of param1.
        param2: Description of param2 (default: 10).

    Returns:
        Description of return value.

    Raises:
        ValueError: When param1 is invalid.

    Example:
        >>> result = example_function("test", 20)
        >>> print(result)
        True
    """
    pass

Documentation site​

User-facing docs are this Docusaurus site. Edit markdown in docs/docs/, then:

cd docs
npm install
npm start          # local preview
npm run build      # production build (also `make docs`)

See the docs README and GitHub Pages setup. The published site is https://datenoio.github.io/undatum/.

Testing​

Running Tests​

Run all tests:

pytest

Run with coverage:

pytest --cov=undatum --cov-report=html

Writing Tests​

  • Place tests in the tests/ directory
  • Test files should be named test_*.py
  • Use descriptive test function names: test_function_name_scenario

Pull Request Process​

  1. Create a branch: Create a feature branch from master

    git checkout -b feature/your-feature-name

  2. Make changes: Make your changes following the code style guidelines

  3. Run checks: Ensure all checks pass:

    black undatum/
    ruff check undatum/
    mypy undatum/
    pytest

  4. Commit: Write clear commit messages following conventional commits:

    feat: add new feature
    fix: fix bug in converter
    docs: update README
    refactor: improve performance

  5. Push: Push your branch and create a pull request

  6. Review: Address any feedback from reviewers

Code Review Guidelines​

  • All code must be reviewed before merging
  • Ensure tests pass and coverage is maintained
  • Follow the existing code style
  • Add documentation for new features
  • Update CHANGELOG.md for user-facing changes

Reporting Issues​

When reporting issues, please include:

  • Description of the issue
  • Steps to reproduce
  • Expected behavior
  • Actual behavior
  • Python version
  • undatum version
  • Relevant error messages or logs

Questions?​

Feel free to open an issue for questions or reach out to the maintainers.

Community​

  • Prefer GitHub Discussions for Q&A and ideas; use Issues for bugs and actionable feature requests. See Community.
  • Look for the good first issue label when getting started.
  • External contributors are welcome — undatum has persistent usage but historically few PRs; small focused patches (tests, docs, install fixes) are especially helpful.
  • Dependency-bot PRs should be auto-merged for patch-level security bumps or closed promptly rather than left unattended.

Release discipline (CLI stability)​

  • Follow semver for user-facing CLI changes.
  • Call out breaking command/flag changes loudly in CHANGELOG.md.
  • Prefer deprecation warnings before removing flags that agents or scripts may depend on.
  • Keep a stable-command guarantee for core verbs (convert, stats, validate, select) whenever possible.