Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
302 lines (212 loc) · 5.86 KB

CONTRIBUTING.md

File metadata and controls

302 lines (212 loc) · 5.86 KB

Contributing to pingping

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

Prerequisites

Before you begin, ensure you have the following tools installed:

Required Tools

  • uv - Fast Python package installer and resolver

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

# Or using pip
pip install uv

  • Git - Version control system

  • Python 3.9+ - The project requires Python 3.9 or higher

Development Setup

1. Fork and Clone the Repository

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/pingping.git
cd pingping

2. Create a Virtual Environment with uv

uv automatically manages virtual environments. Simply sync the project:

# This will create a virtual environment and install all dependencies
uv sync --all-extras

# Or using Makefile
make install

The virtual environment will be created in .venv/ directory.

3. Install Development Dependencies

Development dependencies are already included when you use --all-extras:

  • pytest - Testing framework
  • pytest-cov - Coverage plugin for pytest
  • ruff - Fast Python linter
  • black - Code formatter
  • testiq - Test quality analysis tool Using Makefile (R

Using Makefile:

# Run all tests
make test

# Run with verbose output
make test-verbose

# Run with coverage
make coverage

Using uv directly:ecommended)

The project includes a Makefile for common tasks: Using Makefile (Recommended)

# Run linter
make lint

# Auto-fix linting issues
make lint-fix

# Format code
make format

# Check formatting without changes
make format-check

# Run all checks
make all

Using uv directly

# Show all available commands
make

# Run tests
make test

# Run linter and auto-fix issues
make lint-fix
Using Makefile (Recommended)

```bash
# Run testiq analysis
make testiq

# Get test quality score
make testiq-score

# Generate HTML report
make testiq-html
open testiq_report.html

Using uv directly

Format code

make format

Run all quality checks

make all

Run CI checks locally

make ci

Clean up generated files

make clean


### 
## Development Workflow

### Running Tests

```bash
# Run all tests with coverage
uv run pytest

# Run tests with verbose output
uv run pytest -v

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

# Run specific test
uv run pytest tests/test_ping.py::TestPing::test_ping_en

Code Quality Checks

Linting with Ruff

# Cmake all
   # Or individually:
   make lint-fix
   make format
   make 
# Auto-fix linting issues
uv run ruff check . --fix

Code Formatting with Black

# Check if code is formatted
uv run black --check .

# Format code
uv run black .

Run All Quality Checks

# Lint, format, and test in one go
uv run ruff check . --fix && uv run black . && uv run pytest

Test Quality Analysis with TestIQ

TestIQ helps identify duplicate and redundant tests:

Generate Coverage Data

# Generate TestIQ coverage data
uv run pytest --testiq-output=testiq_coverage.json

Analyze Test Duplicates

# Analyze for duplicate tests (threshold 1.0 skips similarity checks)
uv run testiq analyze testiq_coverage.json --threshold 1.0

# Get test quality score
uv run testiq quality-score testiq_coverage.json

# Run demo to see how it works
uv run testiq demo

View HTML Coverage Report

# Generate HTML coverage report
uv run pytest --cov=pingping --cov-report=html

# Open the report in your browser
open htmlcov/index.html

Generate TestIQ HTML Report

# Generate TestIQ HTML report with duplicate test analysis (skip similarity with threshold 1.0)
uv run testiq analyze testiq_coverage.json --threshold 1.0 --format html --output testiq_report.html

# Open the report in your browser
open testiq_report.html

Making Changes

  1. Create a new branch for your feature or bugfix:

    git checkout -b feature/your-feature-name

  2. Make your changes and ensure they follow the project's coding standards

  3. Run tests and quality checks:

    uv run ruff check . --fix
uv run black .
uv run pytest

  4. Commit your changes with a clear commit message:

    git add .
git commit -m "Add: brief description of your changes"

  5. Push to your fork:

    git push origin feature/your-feature-name

  6. Create a Pull Request on GitHub

Commit Message Guidelines

Use clear and descriptive commit messages:

  • Add: new feature or functionality
  • Fix: bug fix
  • Update: updates to existing features
  • Refactor: code refactoring
  • Docs: documentation changes
  • Test: test-related changes

Code Style Guidelines

  • Follow PEP 8 style guide (enforced by ruff and black)
  • Line length: 100 characters
  • Use type hints where appropriate
  • Write descriptive docstrings for functions and classes
  • Keep functions focused and concise

Testing Guidelines

  • Write tests for new features
  • Ensure all tests pass before submitting PR
  • Maintain or improve code coverage
  • Use descriptive test names
  • Test both success and failure cases

Adding New Language Support

To add support for a new language's ping output:

  1. Create a JSON file in data/ directory (e.g., ping_german.json)
  2. Add sample ping outputs in the new language
  3. Add corresponding test in tests/test_ping.py
  4. Run tests to verify parsing works correctly

Getting Help

  • Open an issue on GitHub for bugs or feature requests
  • Check existing issues and pull requests first
  • Ask questions in issue discussions

License

By contributing to pingping, you agree that your contributions will be licensed under the MIT License.