Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (97 loc) · 3.5 KB

CONTRIBUTING.md

File metadata and controls

135 lines (97 loc) · 3.5 KB

Contributing to LocaleSync

Thank you for your interest in contributing! This document provides guidelines and information for contributors.

Getting Started

Prerequisites

  • Python 3.12 or higher
  • Git

Setting Up the Development Environment

# 1. Clone the repository
git clone https://github.com/polprog-tech/LocaleSync.git
cd LocaleSync

# 2. (Recommended) Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 3. Install in editable mode with dev dependencies
pip install -e ".[dev]"

# 4. Verify the installation
locale-sync --version
pytest

Development Workflow

Running Tests

# All tests
pytest

# With verbose output
pytest -v

# With coverage
pytest --cov=locale_sync --cov-report=term-missing

# Specific test file or class
pytest tests/unit/domain/test_models.py
pytest tests/unit/domain/test_models.py::TestLocaleKey

Linting

ruff check src/ tests/
ruff format --check src/ tests/

# Auto-fix
ruff check --fix src/ tests/
ruff format src/ tests/

Testing with the Playground

locale-sync scan playground/locales
locale-sync check playground/locales
locale-sync sync playground/locales --dry-run

Architecture

Please read docs/architecture.md before making changes. Key principles:

  1. Domain layer (src/locale_sync/domain/) has zero external dependencies
  2. Application layer orchestrates but does not import infrastructure directly at module level
  3. Infrastructure layer implements domain contracts (Protocols)
  4. CLI layer is a thin adapter between user input and application use cases

Where to Put New Code

What Where
New model/value object domain/models.py
New contract/interface domain/contracts.py
New exception type domain/exceptions.py
New file format parser infrastructure/parsers/
New file format writer infrastructure/writers/
New translation provider infrastructure/translators/
New report format infrastructure/reporters/
New CLI command cli/commands/
New use case application/

Adding a Translation Provider

See docs/extensibility.md for detailed guidance.

Pull Request Process

  1. Fork the repository and create a feature branch from main
  2. Make your changes following the architecture guidelines
  3. Add tests for new functionality
  4. Ensure all tests pass: pytest
  5. Ensure linting passes: ruff check src/ tests/
  6. Update documentation if needed
  7. Submit a pull request using the PR template

Commit Messages

Use conventional commit style:

feat: add YAML format support
fix: handle empty nested objects in JSON parser
docs: update extensibility guide with YAML example
test: add edge case tests for placeholder detection
refactor: extract common file resolution logic

Code Style

  • Full type hints on all function signatures
  • Docstrings on public classes and functions
  • Use from __future__ import annotations in all modules
  • Follow existing patterns in the codebase
  • Let ruff handle formatting

Reporting Issues

Use the GitHub issue templates:

  • Bug reports - include reproduction steps, expected vs actual behavior, and environment details
  • Feature requests - describe the problem, proposed solution, and alternatives considered

License

By contributing, you agree that your contributions will be licensed under the same license as the project (AGPL-3.0).