CONTRIBUTING.md•7.55 kB
# Contributing to PrestaShop MCP Server
Thank you for your interest in contributing to the PrestaShop MCP Server! This document provides guidelines and instructions for contributing.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Pull Request Process](#pull-request-process)
- [Reporting Issues](#reporting-issues)
## Code of Conduct
This project follows a Code of Conduct that all contributors are expected to adhere to:
- Be respectful and inclusive
- Welcome newcomers and help them get started
- Focus on constructive criticism
- Assume good intentions
## Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/YOUR-USERNAME/prestashop-mcp.git
cd prestashop-mcp
```
3. **Add the upstream remote**:
```bash
git remote add upstream https://github.com/florinel-chis/prestashop-mcp.git
```
## Development Setup
### Prerequisites
- Python 3.10 or higher
- pip package manager
- Git
### Installation
1. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
2. Install the package in development mode:
```bash
pip install -e ".[dev]"
```
3. Verify installation:
```bash
pytest tests/
python -m prestashop_mcp.ingest
```
## How to Contribute
### Types of Contributions
We welcome various types of contributions:
- **Bug fixes**: Fix issues reported in the issue tracker
- **New features**: Implement new functionality (discuss first in an issue)
- **Documentation**: Improve README, docstrings, or add examples
- **Tests**: Add or improve test coverage
- **Performance**: Optimize existing code
- **Tooling**: Improve development tools and workflows
### Before Starting
1. **Check existing issues** to see if someone is already working on it
2. **Open an issue** to discuss significant changes before starting work
3. **Keep changes focused**: One feature/fix per pull request
## Coding Standards
### Python Style Guide
We follow PEP 8 with these tools:
- **Black** for code formatting (line length: 88)
- **Flake8** for linting
- **Type hints** where appropriate
### Format Your Code
Before committing, run:
```bash
# Format with Black
black prestashop_mcp/ tests/
# Check with Flake8
flake8 prestashop_mcp/ tests/
```
### Code Organization
- **Module structure**: Keep modules focused and single-purpose
- **Functions**: Write small, testable functions
- **Documentation**: Add docstrings to all public functions/classes
- **Type hints**: Use them for function signatures
Example:
```python
def search_hooks(
queries: List[str],
hook_type: Optional[str] = None,
origin: Optional[str] = None,
limit: int = 10,
) -> List[Dict]:
"""Search PrestaShop hooks using FTS5.
Args:
queries: List of search terms
hook_type: Filter by hook type (display, action)
origin: Filter by origin (core, module, theme)
limit: Maximum number of results
Returns:
List of matching hooks with metadata
"""
# Implementation
```
## Testing
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=prestashop_mcp
# Run specific test file
pytest tests/test_ingest.py
# Run specific test
pytest tests/test_ingest.py::test_parse_hook_file
```
### Writing Tests
- Add tests for all new functionality
- Follow existing test patterns in `tests/`
- Use descriptive test names
- Include docstrings explaining what the test verifies
Example:
```python
def test_search_with_filters():
"""Test that search correctly applies hook type and origin filters."""
results = search_hooks(
queries=["product"],
hook_type="action",
origin="core"
)
# Verify all results match filters
for hook in results:
assert hook["type"] == "action"
assert hook["origin"] == "core"
```
### Test Coverage
- Aim for >80% code coverage
- Focus on critical paths and edge cases
- Test error handling and invalid inputs
## Pull Request Process
### 1. Create a Branch
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number-description
```
Branch naming conventions:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation changes
- `test/` - Test additions/improvements
- `refactor/` - Code refactoring
### 2. Make Your Changes
- Write clear, focused commits
- Follow coding standards
- Add/update tests
- Update documentation
### 3. Commit Your Changes
Write clear commit messages:
```bash
git commit -m "Add search filter for module hooks
- Implement origin filter in search_hooks()
- Add tests for module-specific searches
- Update documentation with examples"
```
Commit message format:
- First line: Summary (50 chars or less)
- Blank line
- Detailed description with bullet points
### 4. Keep Your Branch Updated
```bash
git fetch upstream
git rebase upstream/main
```
### 5. Run Tests and Formatting
```bash
# Format code
black prestashop_mcp/ tests/
# Run tests
pytest
# Check coverage
pytest --cov=prestashop_mcp
```
### 6. Push to Your Fork
```bash
git push origin feature/your-feature-name
```
### 7. Open a Pull Request
1. Go to the repository on GitHub
2. Click "New Pull Request"
3. Select your fork and branch
4. Fill out the PR template:
- **Title**: Clear, descriptive summary
- **Description**: What, why, and how
- **Issue**: Link related issues
- **Testing**: How you tested the changes
- **Screenshots**: If applicable
### Pull Request Checklist
Before submitting, ensure:
- [ ] Code follows style guidelines (Black formatted)
- [ ] All tests pass (`pytest`)
- [ ] New code has tests
- [ ] Documentation is updated
- [ ] Commit messages are clear
- [ ] Branch is up to date with main
- [ ] No merge conflicts
## Reporting Issues
### Bug Reports
When reporting bugs, include:
1. **Description**: Clear description of the bug
2. **Steps to reproduce**: Exact steps to trigger the bug
3. **Expected behavior**: What should happen
4. **Actual behavior**: What actually happens
5. **Environment**:
- OS (macOS, Windows, Linux)
- Python version
- Package version
6. **Logs**: Relevant error messages or logs
7. **Additional context**: Any other relevant information
### Feature Requests
When requesting features, include:
1. **Use case**: Why do you need this feature?
2. **Proposed solution**: How should it work?
3. **Alternatives**: Any alternative solutions you've considered
4. **Additional context**: Examples, mockups, etc.
## Development Roadmap
Current focus areas:
- **Phase 1 (MVP)**: ✅ Hooks documentation (648 hooks)
- **Phase 2**: Modules and components documentation
- **Phase 3**: Themes and API documentation
- **Phase 4**: Performance optimization and v1.0.0
See [open issues](https://github.com/florinel-chis/prestashop-mcp/issues) for planned features and improvements.
## Questions?
- **Issues**: [GitHub Issues](https://github.com/florinel-chis/prestashop-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/florinel-chis/prestashop-mcp/discussions)
## Recognition
Contributors will be:
- Listed in CHANGELOG.md
- Acknowledged in release notes
- Added to the project's contributors list
Thank you for contributing to PrestaShop MCP Server! 🎉