CONTRIBUTING.md•7.88 kB
# Contributing to Shopify Liquid MCP Server
Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.
## Code of Conduct
Be respectful, inclusive, and constructive. We're all here to build better tools for the Shopify theme development community.
## How Can I Contribute?
### Reporting Bugs
Found a bug? Please open an issue with:
- **Clear title** - Describe the problem concisely
- **Steps to reproduce** - How can we trigger the bug?
- **Expected behavior** - What should happen?
- **Actual behavior** - What actually happens?
- **Environment** - OS, Python version, installation method
- **Logs** - Any relevant error messages
**Example:**
```
Title: Search returns no results for "product"
Steps:
1. Start MCP server
2. Call search_liquid_docs(["product"])
3. Receive empty results
Expected: Should return product-related documentation
Actual: Returns []
Environment: macOS 14.0, Python 3.10, pip install
```
### Suggesting Features
Have an idea? Open an issue with:
- **Use case** - Why is this feature needed?
- **Proposed solution** - How should it work?
- **Alternatives** - What other approaches did you consider?
- **Examples** - Show how it would be used
### Improving Documentation
Documentation improvements are always welcome:
- Fix typos or unclear explanations
- Add more examples
- Improve setup instructions
- Create tutorials or guides
### Adding Documentation
Have custom Liquid snippets or patterns to share?
1. Add `.md` files to `custom-docs/` folder
2. Follow existing documentation format
3. Include code examples
4. Submit a PR
## Development Setup
### 1. Fork and Clone
```bash
# Fork on GitHub, then:
git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp
```
### 2. Create Virtual Environment
```bash
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
```
### 3. Install Development Dependencies
```bash
pip install -e ".[dev]"
```
This installs:
- pytest - Testing framework
- pytest-cov - Code coverage
- black - Code formatter
- flake8 - Linter
- mypy - Type checker
### 4. Run Tests
```bash
# All tests
pytest
# With coverage
pytest --cov=shopify_liquid_mcp
# Specific test
pytest tests/test_ingest.py -v
# Watch mode
pytest-watch
```
### 5. Code Quality
```bash
# Format code
black shopify_liquid_mcp/
# Lint
flake8 shopify_liquid_mcp/
# Type check
mypy shopify_liquid_mcp/
# All checks
./scripts/check.sh
```
## Making Changes
### 1. Create a Branch
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```
Branch naming:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation
- `refactor/` - Code refactoring
- `test/` - Test improvements
### 2. Make Your Changes
Follow these guidelines:
**Code Style:**
- Use Black for formatting (line length 88)
- Follow PEP 8
- Add type hints
- Write docstrings (Google style)
**Example:**
```python
def search_documentation(queries: List[str], limit: int = 10) -> List[Dict[str, str]]:
"""Search documentation using FTS5.
Args:
queries: List of search terms
limit: Maximum number of results to return
Returns:
List of matching documents with metadata
Example:
>>> search_documentation(["for", "loop"])
[{"name": "for", "title": "For Loop", ...}]
"""
# Implementation
```
**Tests:**
- Add tests for new features
- Fix any broken tests
- Aim for >80% coverage
**Documentation:**
- Update README if needed
- Add docstrings
- Update CHANGELOG.md
### 3. Commit Your Changes
```bash
git add .
git commit -m "feat: add new search feature"
```
Commit message format:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `style:` - Formatting
- `refactor:` - Code restructuring
- `test:` - Tests
- `chore:` - Maintenance
**Examples:**
```
feat: add fuzzy search support
fix: handle empty search queries
docs: update installation instructions
test: add tests for get_document
```
### 4. Push and Create PR
```bash
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub with:
- **Clear title** - Summarize the changes
- **Description** - Explain what and why
- **Related issues** - Link to issues (Fixes #123)
- **Testing** - How did you test this?
- **Screenshots** - If applicable
**PR Template:**
```markdown
## Description
Brief description of changes
## Related Issues
Fixes #123
## Changes
- Added X feature
- Fixed Y bug
- Updated Z documentation
## Testing
- [ ] All tests pass
- [ ] Added new tests
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-reviewed code
- [ ] Commented complex code
- [ ] Updated documentation
- [ ] No new warnings
```
## Development Guidelines
### Project Structure
```
shopify-liquid-mcp/
├── shopify_liquid_mcp/ # Main package
│ ├── __init__.py
│ ├── config.py # Configuration
│ ├── ingest.py # Documentation indexing
│ └── server.py # MCP server implementation
├── tests/ # Test suite
│ ├── test_ingest.py
│ └── test_server.py
├── docs/ # Documentation
├── pyproject.toml # Package config
└── README.md
```
### Adding a New Tool
1. Add function to `server.py`:
```python
@mcp.tool()
def my_new_tool(param: str) -> str:
"""Description of what this tool does.
Args:
param: Parameter description
Returns:
Result description
"""
# Implementation
return result
```
2. Add tests in `tests/test_server.py`:
```python
def test_my_new_tool():
result = my_new_tool("test")
assert result == "expected"
```
3. Update README.md with tool documentation
4. Update CHANGELOG.md
### Adding Documentation
1. Place `.md` files in appropriate directory:
- `tags/` - Liquid tags
- `filters/` - Liquid filters
- `objects/` - Liquid objects
2. Follow this format:
```markdown
# Title
## Overview
Brief description
## Syntax
```liquid
code example
```
## Parameters
- **param1**: Description
- **param2**: Description
## Examples
... examples ...
```
3. Reindex:
```bash
python -m shopify_liquid_mcp.ingest --force
```
## Testing
### Writing Tests
```python
import pytest
from shopify_liquid_mcp.ingest import search_documentation
def test_search_basic():
"""Test basic search functionality."""
results = search_documentation(["test"])
assert len(results) > 0
assert "name" in results[0]
def test_search_empty():
"""Test search with empty query."""
results = search_documentation([])
assert results == []
@pytest.fixture
def sample_database():
"""Create temporary test database."""
# Setup
db = create_test_db()
yield db
# Teardown
db.close()
```
### Running Tests
```bash
# Quick test
pytest tests/test_ingest.py::test_search_basic -v
# With output
pytest -s
# Stop on first failure
pytest -x
# Run last failed
pytest --lf
# Coverage report
pytest --cov=shopify_liquid_mcp --cov-report=html
open htmlcov/index.html
```
## Release Process
1. **Update version** in `pyproject.toml`
2. **Update CHANGELOG.md**
3. **Run all tests:** `pytest`
4. **Build:** `python -m build`
5. **Tag:** `git tag v0.2.0`
6. **Push:** `git push --tags`
7. **Create GitHub release**
8. **Publish to PyPI** (maintainers only)
## Questions?
- 💬 [GitHub Discussions](https://github.com/florinel-chis/shopify-liquid-mcp/discussions)
- 🐛 [Issues](https://github.com/florinel-chis/shopify-liquid-mcp/issues)
- 📧 Email: your.email@example.com
## Recognition
Contributors are recognized in:
- README.md Contributors section
- CHANGELOG.md for each release
- GitHub contributors page
Thank you for contributing! 🎉