CONTRIBUTING.md

---

🤝 Contributing Guide

---

Thank you for contributing to Path Header Scanner.

This project aims to provide a clean, professional CLI tool for inserting, validating, and updating file path headers across source code and documentation files.

---

🧭 Principles

All contributions must follow:

• Simplicity
• Readability
• Maintainability
• Consistency

---

🧱 Project Architecture

app/
├── cli/
├── config/
├── constants/
├── core/
├── languages/
├── models/
├── services/
├── templates/
├── theme/
├── ui/
├── utils/
├── __init__.py
├── __version__.py
└── __main__.py

See full structure in project_structure.md.

Each module has a clear responsibility. Avoid mixing concerns.

---

📝 Code Guidelines

1. Documentation (Required)

Every function must include:

def example(arg: str) -> str:
    """
    Short description.

    Args:
        arg (str): Description

    Returns:
        str: Description

    Raises:
        ValueError: Description
    """

2. File-Level Docstring

Each file must start with:

"""
Description of the module.
"""

---

3. Logging (NO print)

Always use:

import logging
logger = logging.getLogger(__name__)

Examples:

logger.info("Processing...")
logger.debug("Details: %s", data)
logger.error("Error occurred: %s", error)

---

4. CLI Behavior

• Must be consistent
• Must not break existing commands
• Must support config + CLI overrides

---

🧪 Testing

(Will be added in future phase)

• Add unit tests for new logic
• Ensure CLI commands work as expected

---

🔄 Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Implement changes
4. Add/update documentation
5. Submit Pull Request

---

📌 Notes

• Keep commits clean and meaningful
• Avoid unnecessary complexity
• Prefer explicit over implicit