Contributing Guide¶

Thank you for your interest in contributing to the fnb project! This guide explains how to contribute to the project effectively.

Development Environment Setup¶

1. Clone the Repository¶

git clone https://gitlab.com/qumasan/fnb.git
cd fnb

2. Development Environment Setup¶

# Setup virtual environment using uv
uv venv

# Install in development mode with all dependencies
uv pip install -e .

# Install development dependencies
uv sync --all-extras

3. Verify Installation¶

# Run tests to ensure everything is working
task test:unit

# Check code formatting
task lint

# Build documentation
task docs:build

Coding Standards¶

Code Style¶

Python 3.12+ features and syntax
Follow PEP 8 coding style
Use type hints for type-safe code
Write comprehensive docstrings (Google style)
Maintain sufficient test coverage (target: 85%+)

Formatting and Linting¶

We use ruff for code formatting and linting:

# Format code automatically
task lint

# Run pre-commit hooks (includes formatting, linting, tests)
task lint:pre-commit

# Check code quality manually
uv run ruff check src tests
uv run ruff format src tests

Documentation¶

Use Google-style docstrings for all functions and classes
Include examples in docstrings where helpful
Update relevant documentation when adding features
Write clear commit messages following Conventional Commits

Development Workflow¶

1. Issue-Driven Development¶

Check existing issues before starting work
Create an issue for new features or bugs
Link pull requests to relevant issues
Use GitLab's issue templates when available

2. Branching Strategy¶

# Create feature branch from main
git checkout -b feature/your-feature-name

# Work on your changes
# ... make changes ...

# Run tests and formatting
task test:ci

# Commit with conventional commit format
git commit -m "feat: add new backup validation feature"

# Push and create merge request
git push origin feature/your-feature-name

3. Merge Request Guidelines¶

Use descriptive titles and descriptions
Include issue references (e.g., "Closes #123")
Ensure all CI checks pass
Add/update tests for new functionality
Update documentation as needed
Request review from maintainers

Testing¶

Test Structure¶

tests/
├── unit/          # Fast unit tests (target: <2s execution)
│   ├── test_cli.py
│   ├── test_config.py
│   ├── test_fetcher.py
│   └── ...
├── integration/   # Integration tests (slower, more comprehensive)
│   └── test_integration.py
└── fixtures/      # Test fixtures and utilities
    └── ...

Running Tests¶

# Run all tests
task test

# Run only unit tests (fast)
task test:unit

# Run only integration tests
task test:integration

# Run tests with coverage report
uv run pytest --cov=fnb --cov-report=html

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

# Run specific test
uv run pytest tests/unit/test_cli.py::test_version_command

Writing Tests¶

Write tests for new features and bug fixes
Follow the existing test patterns
Use descriptive test function names
Include both positive and negative test cases
Mock external dependencies (SSH, filesystem operations)

Example test:

def test_config_validation_success():
    """Test successful configuration validation."""
    config_data = {
        "fetch": {
            "test_task": {
                "label": "test",
                "summary": "Test task",
                "host": "user@host",
                "source": "/remote/path/",
                "target": "./local/path/",
                "options": ["-av"],
                "enabled": True
            }
        }
    }

    config = FnbConfig.model_validate(config_data)
    assert len(config.fetch) == 1
    assert config.fetch["test_task"].label == "test"

Documentation¶

Building Documentation¶

# Serve documentation locally
task docs

# Build static documentation
task docs:build

# The documentation will be available at http://localhost:8000

Documentation Structure¶

docs/
├── index.{en,ja}.md           # Home page
├── installation.{en,ja}.md    # Installation guide
├── usage/                     # User guides
│   ├── quickstart.{en,ja}.md
│   ├── commands.{en,ja}.md
│   └── ...
├── development/               # Developer documentation
│   ├── contributing.{en,ja}.md
│   └── releasing.{en,ja}.md
└── references/                # API and technical references
    ├── api.{en,ja}.md
    └── ...

Writing Documentation¶

Write in clear, concise English
Include practical examples
Use consistent terminology
Update both English and Japanese versions when possible
Test all code examples

Version Management and Releases¶

Version Bumping¶

We use commitizen for version management:

# Preview version bump
task bump-dry

# Execute version bump and update changelog
task bump

# Create GitLab release
task release

Release Process¶

Ensure all tests pass: task test:ci
Update version and changelog: task bump
Create GitLab release: task release
Deploy to PyPI (maintainers only): task publish:prod

GitLab Workflow¶

Using GitLab CLI (glab)¶

# View issues
glab issue list

# Create merge request
glab mr create --title "feat: add new feature" --description "Closes #123"

# View merge request status
glab mr status

# Check CI pipeline
glab ci status

Issue Templates¶

Use the provided issue templates for: - Bug reports - Feature requests - Documentation improvements - Performance issues

Code Review Guidelines¶

For Contributors¶

Keep changes focused and atomic
Write clear commit messages
Include tests for new functionality
Update documentation as needed
Respond to review comments promptly

For Reviewers¶

Focus on code quality, not personal preferences
Provide constructive feedback
Test the changes if needed
Check that CI passes
Verify documentation is updated

Common Development Tasks¶

Adding a New CLI Command¶

Add command function in src/fnb/cli.py
Add business logic in appropriate module
Write comprehensive tests
Update documentation
Add usage examples

Adding Configuration Options¶

Update Pydantic models in src/fnb/config.py
Add validation logic
Update configuration documentation
Add tests for validation scenarios
Update example configurations

Fixing Bugs¶

Create a test that reproduces the bug
Fix the bug
Ensure the test passes
Add regression test if needed
Update documentation if behavior changed

Getting Help¶

Communication Channels¶

GitLab Issues: Technical discussions and bug reports
GitLab Merge Requests: Code review discussions
Documentation: In-code docstrings and docs/ directory

Resources¶

Recognition¶

Contributors are recognized in: - Git commit history - Release notes and changelogs - Project documentation

Thank you for contributing to fnb! Your contributions help make backup workflows easier and more reliable for everyone.