tanyar09 d300eb1122 chore: Add configuration and documentation files for project structure and guidelines

This commit introduces several new files to enhance project organization and developer onboarding. The `.cursorignore` and `.cursorrules` files provide guidelines for Cursor AI, while `CONTRIBUTING.md` outlines contribution procedures. Additionally, `IMPORT_FIX_SUMMARY.md`, `RESTRUCTURE_SUMMARY.md`, and `STATUS.md` summarize recent changes and project status. The `README.md` has been updated to reflect the new project focus and structure, ensuring clarity for contributors and users. These additions aim to improve maintainability and facilitate collaboration within the PunimTag project.

2025-10-15 14:43:18 -04:00

10 KiB

Raw Permalink Blame History

Contributing to PunimTag

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

🤝 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Expected Behavior

Be respectful and considerate
Welcome newcomers and help them learn
Accept constructive criticism gracefully
Focus on what's best for the project
Show empathy towards other contributors

Unacceptable Behavior

Harassment or discriminatory language
Trolling or insulting comments
Public or private harassment
Publishing others' private information
Other unprofessional conduct

🚀 Getting Started

Prerequisites

Python 3.12+
Git
Basic understanding of Python and Tkinter
Familiarity with face recognition concepts (helpful)

Setting Up Development Environment

Fork and Clone

git fork <repository-url>
git clone <your-fork-url>
cd punimtag

Create Virtual Environment

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

Install Dependencies

pip install -r requirements.txt
pip install -r requirements-dev.txt  # If available

Verify Installation

python src/gui/dashboard_gui.py

🔄 Development Workflow

Branch Strategy

main/master     - Stable releases
develop         - Integration branch
feature/*       - New features
bugfix/*        - Bug fixes
hotfix/*        - Urgent fixes
release/*       - Release preparation

Creating a Feature Branch

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Making Changes

Make your changes in the appropriate directory:
- Business logic: src/core/
- GUI components: src/gui/
- Utilities: src/utils/
- Tests: tests/
Follow coding standards (see below)
Add/update tests
Update documentation
Test your changes thoroughly

Committing Changes

Use clear, descriptive commit messages:

git add .
git commit -m "feat: add face clustering algorithm"

Commit Message Format:

<type>: <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

feat: add DeepFace integration

- Replace face_recognition with DeepFace
- Implement ArcFace model
- Add cosine similarity matching
- Update database schema

Closes #123

📏 Coding Standards

Python Style Guide

Follow PEP 8 with these specifics:

Formatting

Indentation: 4 spaces (no tabs)
Line Length: 100 characters max (120 for comments)

Imports: Grouped and sorted

# Standard library
import os
import sys

# Third-party
import numpy as np
from PIL import Image

# Local
from src.core.database import DatabaseManager

Naming Conventions

Classes: PascalCase (e.g., FaceProcessor)
Functions/Methods: snake_case (e.g., process_faces)
Constants: UPPER_SNAKE_CASE (e.g., DEFAULT_TOLERANCE)
Private: Prefix with _ (e.g., _internal_method)

Documentation

All public classes and functions must have docstrings:

def process_faces(self, limit: int = 50) -> int:
    """Process unprocessed photos for faces.
    
    Args:
        limit: Maximum number of photos to process
        
    Returns:
        Number of photos successfully processed
        
    Raises:
        DatabaseError: If database connection fails
    """
    pass

Type Hints

Use type hints for all function signatures:

from typing import List, Dict, Optional

def get_similar_faces(
    self, 
    face_id: int, 
    tolerance: float = 0.6
) -> List[Dict[str, Any]]:
    pass

Code Organization

File Structure

#!/usr/bin/env python3
"""
Module description
"""

# Imports
import os
from typing import List

# Constants
DEFAULT_VALUE = 42

# Classes
class MyClass:
    """Class description"""
    pass

# Functions
def my_function():
    """Function description"""
    pass

# Main execution
if __name__ == "__main__":
    main()

Error Handling

Always use specific exception types:

try:
    result = risky_operation()
except FileNotFoundError as e:
    logger.error(f"File not found: {e}")
    raise
except ValueError as e:
    logger.warning(f"Invalid value: {e}")
    return default_value

🧪 Testing

Writing Tests

Create tests in tests/ directory:

import pytest
from src.core.face_processing import FaceProcessor

def test_face_detection():
    """Test face detection on sample image"""
    processor = FaceProcessor(db_manager, verbose=0)
    result = processor.process_faces(limit=1)
    assert result > 0

def test_similarity_calculation():
    """Test face similarity metric"""
    processor = FaceProcessor(db_manager, verbose=0)
    similarity = processor._calculate_cosine_similarity(enc1, enc2)
    assert 0.0 <= similarity <= 1.0

Running Tests

# All tests
python -m pytest tests/

# Specific test file
python tests/test_face_recognition.py

# With coverage
pytest --cov=src tests/

# Verbose output
pytest -v tests/

Test Guidelines

Test Coverage: Aim for >80% code coverage
Test Names: Descriptive names starting with test_
Assertions: Use clear assertion messages
Fixtures: Use pytest fixtures for setup/teardown
Isolation: Tests should not depend on each other

📚 Documentation

What to Document

Code Changes: Update docstrings
API Changes: Update API documentation
New Features: Add to README and docs
Breaking Changes: Clearly mark in changelog
Architecture: Update ARCHITECTURE.md if needed

Documentation Style

Use Markdown for all documentation
Include code examples
Add diagrams where helpful
Keep language clear and concise
Update table of contents

Files to Update

README.md: User-facing documentation
docs/ARCHITECTURE.md: Technical architecture
.notes/task_list.md: Task tracking
Inline comments: Complex logic explanation

🔀 Pull Request Process

Before Submitting

Code follows style guidelines
All tests pass
New tests added for new features
Documentation updated
No linting errors
Commit messages are clear
Branch is up to date with develop

Submitting PR

Push your branch

git push origin feature/your-feature-name

Create Pull Request
- Go to GitHub/GitLab
- Click "New Pull Request"
- Select your feature branch
- Fill out PR template
PR Title Format

[Type] Short description

Examples:
[Feature] Add DeepFace integration
[Bug Fix] Fix face detection on rotated images
[Docs] Update architecture documentation

PR Description Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Closes #123

## Testing
Describe testing performed

## Screenshots (if applicable)
Add screenshots

## Checklist
- [ ] Code follows style guidelines
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] All tests pass

Review Process

Automated Checks: Must pass all CI/CD checks
Code Review: At least one approval required
Discussion: Address all review comments
Updates: Make requested changes
Approval: Merge after approval

After Merge

Delete feature branch
Pull latest develop
Update local repository

🏗️ Project Structure

Key Directories

src/
├── core/          # Business logic - most changes here
├── gui/           # GUI components - UI changes here
└── utils/         # Utilities - helper functions

tests/             # All tests go here

docs/              # User documentation
.notes/            # Developer notes

Module Dependencies

gui → core → database
gui → utils
core → utils

Rules:

Core modules should not import GUI modules
Utils should not import core or GUI
Avoid circular dependencies

💡 Tips for Contributors

Finding Issues to Work On

Look for good first issue label
Check .notes/task_list.md
Ask in discussions

Getting Help

Read documentation first
Check existing issues
Ask in discussions
Contact maintainers

Best Practices

Start Small: Begin with small changes
One Feature: One PR = one feature
Test Early: Write tests as you code
Ask Questions: Better to ask than assume
Be Patient: Reviews take time

🎯 Areas Needing Contribution

High Priority

DeepFace integration
Test coverage improvement
Performance optimization
Documentation updates

Medium Priority

GUI improvements
Additional search filters
Export functionality
Backup/restore features

Low Priority

Code refactoring
Style improvements
Additional themes
Internationalization

📞 Contact

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [Add email]

🙏 Recognition

Contributors will be:

Listed in AUTHORS file
Mentioned in release notes
Thanked in documentation

📄 License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for contributing to PunimTag! 🎉

Every contribution, no matter how small, makes a difference!

10 KiB Raw Permalink Blame History