Contributing Guide

This guide explains how to contribute to the CountryFlag project.

Setting Up Development Environment

1. Fork and Clone

First, fork the repository on GitHub, then clone your fork:

git clone https://github.com/yourusername/countryflag.git
cd countryflag

2. Create Virtual Environment

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

Install development dependencies:

pip install -e ".[dev]"

4. Install Pre-commit Hooks

Set up pre-commit hooks:

pre-commit install

Making Changes

1. Create a Branch

Create a branch for your changes:

git checkout -b feature/your-feature-name

2. Code Style

  • Follow PEP 8 guidelines

  • Use type hints

  • Write docstrings in Google style

  • Keep lines under 88 characters

  • Run black for code formatting

3. Testing

Run tests before submitting changes:

# Run all tests
pytest

# Run specific test categories
pytest tests/unit/
pytest tests/property/
pytest tests/performance/

4. Documentation

Update documentation for any changes:

# Build documentation
sphinx-build -b html docs/source docs/build/html

Submitting Changes

1. Commit Changes

Follow commit message guidelines:

git add .
git commit -m "feat: add new feature"

2. Push Changes

Push to your fork:

git push origin feature/your-feature-name

3. Create Pull Request

Create a pull request on GitHub with:

  • Clear description of changes

  • Link to any related issues

  • Screenshots if applicable

  • Test results

Code Review Process

1. Automated Checks

Your PR will be checked for:

  • Test coverage

  • Code style

  • Type checking

  • Documentation

2. Manual Review

A maintainer will review your PR for:

  • Code quality

  • Test coverage

  • Documentation

  • Overall design

3. Feedback

  • Address any feedback promptly

  • Keep discussions focused

  • Ask questions if unclear

Development Guidelines

1. Code Organization

  • Keep modules focused

  • Follow existing structure

  • Use appropriate abstractions

2. Testing

  • Write unit tests for new code

  • Add property tests for complex logic

  • Include performance tests when relevant

3. Documentation

  • Update API documentation

  • Add examples for new features

  • Keep README.md current

4. Performance

  • Consider caching where appropriate

  • Profile code changes

  • Test with large datasets

5. Security

  • Never commit secrets

  • Validate all inputs

  • Use safe defaults

Getting Help

  • Create an issue for bugs

  • Ask questions in discussions

  • Join our community chat

Release Process

1. Version Updates

Update version in:

  • pyproject.toml

  • setup.py

  • __init__.py

2. Documentation

  • Update docs/CHANGELOG.md

  • Review all documentation

  • Update version references

3. Testing

Run full test suite:

tox

4. Create Release

  • Create and push tag

  • Create GitHub release

  • Upload to PyPI

5. Announcements

  • Update documentation site

  • Announce in discussions

  • Update any related projects