CONTRIBUTING.md•7.21 kB
# Contributing to SCS-MCP
Thank you for your interest in contributing to SCS-MCP! We welcome contributions from the community and are excited to work with you.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [How to Contribute](#how-to-contribute)
- [Pull Request Process](#pull-request-process)
- [Coding Standards](#coding-standards)
- [Testing Guidelines](#testing-guidelines)
- [Documentation](#documentation)
- [Community](#community)
## Code of Conduct
We are committed to providing a welcoming and inclusive environment. Please:
- Be respectful and considerate
- Welcome newcomers and help them get started
- Focus on constructive criticism
- Respect differing viewpoints and experiences
## Getting Started
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/YOUR_FORK_USERNAME/scs-mcp.git
cd scs-mcp
```
3. **Add upstream remote**:
```bash
git remote add upstream https://github.com/StevenJJobson/scs-mcp.git
```
## Development Setup
### Python Environment
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Install pre-commit hooks
pre-commit install
```
### Node.js Environment (for Voice Assistant)
```bash
cd voice-assistant
npm install
npm run setup
```
### Running Tests
```bash
# Python tests
pytest tests/ -v --cov=src
# Voice assistant tests
cd voice-assistant && npm test
# Linting
flake8 src/
black --check src/
mypy src/
```
## How to Contribute
### Reporting Bugs
1. **Check existing issues** to avoid duplicates
2. **Create a new issue** with:
- Clear, descriptive title
- Steps to reproduce
- Expected vs actual behavior
- System information
- Error messages/logs
### Suggesting Features
1. **Check the roadmap** and existing feature requests
2. **Open a discussion** first for major features
3. **Create a feature request** with:
- Use case description
- Proposed solution
- Alternative solutions considered
- Mockups/examples if applicable
### Contributing Code
1. **Find an issue** labeled `good first issue` or `help wanted`
2. **Comment on the issue** to claim it
3. **Create a feature branch**:
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes** following our coding standards
5. **Write/update tests** for your changes
6. **Update documentation** if needed
7. **Commit your changes** with clear messages
## Pull Request Process
### Before Submitting
- [ ] Tests pass locally (`pytest`, `npm test`)
- [ ] Code follows style guidelines (`black`, `flake8`)
- [ ] Documentation is updated
- [ ] Commit messages are clear and descriptive
- [ ] Branch is up-to-date with main
### PR Guidelines
1. **Title**: Use conventional commits format
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation
- `test:` Testing
- `refactor:` Code refactoring
- `perf:` Performance improvement
2. **Description**: Include:
- What changes were made
- Why changes were necessary
- Related issue numbers
- Screenshots if UI changes
3. **Size**: Keep PRs focused and reasonably sized
### Review Process
1. Automated tests run via GitHub Actions
2. Code review by maintainers
3. Address feedback and update PR
4. Maintainer merges when approved
## Coding Standards
### Python
```python
# Use type hints
def search(query: str, limit: int = 10) -> List[SearchResult]:
"""
Search for code using semantic similarity.
Args:
query: Search query text
limit: Maximum results to return
Returns:
List of search results
"""
pass
# Follow PEP 8
# Use black for formatting
# Maximum line length: 88 characters
```
### JavaScript/TypeScript
```javascript
// Use ESLint configuration
// Prefer const/let over var
// Use async/await over callbacks
// Document with JSDoc
/**
* Handle voice command
* @param {string} command - Voice command text
* @returns {Promise<Response>} Command response
*/
async function handleVoiceCommand(command) {
// Implementation
}
```
### Commit Messages
```
feat: Add semantic search for git history
- Implement git commit indexing
- Add search by commit message
- Include author and date filters
Fixes #123
```
## Testing Guidelines
### Unit Tests
```python
def test_search_returns_results():
"""Test that search returns expected results."""
engine = SearchEngine()
results = engine.search("authentication")
assert len(results) > 0
assert results[0].score > 0.5
```
### Integration Tests
```python
@pytest.mark.integration
async def test_mcp_server_handles_request():
"""Test MCP server request handling."""
server = MCPServer()
response = await server.handle_request({
"method": "search",
"params": {"query": "test"}
})
assert response["status"] == "success"
```
### Test Coverage
- Aim for >80% code coverage
- Test edge cases and error conditions
- Include performance tests for critical paths
## Documentation
### Code Documentation
- Add docstrings to all public functions/classes
- Include type hints
- Provide usage examples
### User Documentation
- Update README for new features
- Add to API.md for new tools
- Include in CHANGELOG.md
### Examples
When adding new features, include:
- Code examples in documentation
- Sample configuration
- Common use cases
## Community
### Getting Help
- **Discord**: [Join our server](https://discord.gg/scs-mcp)
- **GitHub Discussions**: Ask questions and share ideas
- **Stack Overflow**: Tag with `scs-mcp`
### Maintainers
- Review [MAINTAINERS.md](MAINTAINERS.md) for team contacts
- Ping @maintainers for urgent issues
### Recognition
Contributors are recognized in:
- [CONTRIBUTORS.md](CONTRIBUTORS.md)
- Release notes
- Project README
## Development Workflow
### Feature Development
```bash
# 1. Sync with upstream
git fetch upstream
git checkout main
git merge upstream/main
# 2. Create feature branch
git checkout -b feature/new-feature
# 3. Make changes and test
# ... edit files ...
pytest tests/
# 4. Commit changes
git add .
git commit -m "feat: Add new feature"
# 5. Push to your fork
git push origin feature/new-feature
# 6. Create pull request on GitHub
```
### Bug Fixes
```bash
# 1. Create bugfix branch
git checkout -b fix/issue-description
# 2. Fix and test
# ... fix bug ...
pytest tests/test_affected_area.py
# 3. Commit with issue reference
git commit -m "fix: Resolve issue with search caching
Fixes #456"
# 4. Submit PR
```
## Release Process
1. Version bump in `setup.py` and `package.json`
2. Update CHANGELOG.md
3. Create release PR
4. Tag release after merge
5. Publish to PyPI and npm
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
## Questions?
Feel free to:
- Open an issue for clarification
- Ask in GitHub Discussions
- Contact maintainers directly
Thank you for contributing to SCS-MCP! 🎉