Prometheus MCP Server

# Contributing to Prometheus MCP Server Thank you for your interest in contributing to Prometheus MCP Server! We welcome contributions from the community and are grateful for your support. ## Table of Contents - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Reporting Bugs](#reporting-bugs) - [Suggesting Features](#suggesting-features) - [Submitting Pull Requests](#submitting-pull-requests) - [Development Setup](#development-setup) - [Coding Standards](#coding-standards) - [Testing Guidelines](#testing-guidelines) - [Pull Request Process](#pull-request-process) - [Release and Versioning](#release-and-versioning) - [Community and Support](#community-and-support) ## Code of Conduct This project adheres to a code of conduct that all contributors are expected to follow. By participating, you are expected to uphold this code. Please be respectful, inclusive, and considerate in all interactions. ## How Can I Contribute? ### Reporting Bugs Before creating bug reports, please check the [issue tracker](https://github.com/pab1it0/prometheus-mcp-server/issues) to avoid duplicates. When you create a bug report, include as many details as possible: 1. **Use the bug report template** - Fill in [the template](https://github.com/pab1it0/prometheus-mcp-server/issues/new?template=bug_report.yml) 2. **Use a clear and descriptive title** - Summarize the issue in the title 3. **Describe the exact steps to reproduce** - Be specific about what you did 4. **Provide specific examples** - Include code samples or configuration files 5. **Describe the behavior you observed** - Explain what actually happened 6. **Explain the expected behavior** - What you expected to happen instead 7. **Include screenshots** - If applicable, add screenshots to help explain your problem 8. **Specify your environment**: - OS version - Python version - Prometheus version - MCP client being used ### Suggesting Features Feature suggestions are tracked as GitHub issues. When creating a feature suggestion: 1. **Use the feature request template** - Fill in [the template](https://github.com/pab1it0/prometheus-mcp-server/issues/new?template=feature_request.yml) 2. **Use a clear and descriptive title** - Summarize the feature in the title 3. **Provide a detailed description** - Explain the feature and its benefits 4. **Describe the current behavior** - If applicable, describe what currently happens 5. **Describe the proposed behavior** - Explain how the feature would work 6. **Explain why this would be useful** - Describe the use cases and benefits 7. **List alternatives considered** - If you've thought of other solutions, mention them ### Submitting Pull Requests We actively welcome your pull requests! Here's how to contribute code: 1. **Fork the repository** and create your branch from `main` 2. **Make your changes** following our [coding standards](#coding-standards) 3. **Add tests** for any new functionality 4. **Ensure all tests pass** and maintain or improve code coverage 5. **Update documentation** if you've changed functionality 6. **Submit a pull request** with a clear description of your changes ## Development Setup This project uses [`uv`](https://github.com/astral-sh/uv) for dependency management. Follow these steps to set up your development environment: ### Prerequisites - Python 3.10 or higher - A running Prometheus server (for testing) - Git ### Installation 1. **Install uv**: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` 2. **Clone your fork**: ```bash git clone https://github.com/YOUR_USERNAME/prometheus-mcp-server.git cd prometheus-mcp-server ``` 3. **Create and activate a virtual environment**: ```bash uv venv source .venv/bin/activate # On Unix/macOS .venv\Scripts\activate # On Windows ``` 4. **Install dependencies**: ```bash # Install the package in editable mode with dev dependencies uv pip install -e ".[dev]" ``` 5. **Set up environment variables**: ```bash cp .env.template .env # Edit .env with your Prometheus URL and credentials ``` ## Coding Standards Please follow these guidelines when writing code: ### Python Style Guide - Follow [PEP 8](https://peps.python.org/pep-0008/) style guide - Use meaningful variable and function names - Write docstrings for all public modules, functions, classes, and methods - Keep functions focused and single-purpose - Maximum line length: 100 characters (when practical) ### Code Organization - Place new functionality in appropriate modules - Keep related code together - Avoid circular dependencies - Use type hints where appropriate ### Documentation - Update the README.md if you change functionality - Add docstrings to new functions and classes - Comment complex logic or non-obvious implementations - Keep comments up-to-date with code changes ### Commit Messages Write clear, concise commit messages: - Use the present tense ("Add feature" not "Added feature") - Use the imperative mood ("Move cursor to..." not "Moves cursor to...") - Limit the first line to 72 characters or less - Reference issues and pull requests when relevant - For example: ``` feat: add support for custom headers in Prometheus requests - Adds PROMETHEUS_CUSTOM_HEADERS environment variable - Updates documentation with usage examples - Includes tests for header validation Fixes #106 ``` ## Testing Guidelines All contributions must include appropriate tests. We use `pytest` for testing. ### Running Tests ```bash # Run all tests pytest # Run with coverage report pytest --cov=src --cov-report=term-missing # Run specific test file pytest tests/test_specific.py # Run tests matching a pattern pytest -k "test_pattern" ``` ### Test Requirements - **Write tests for new features** - All new functionality must have corresponding tests - **Maintain code coverage** - Aim for 80%+ code coverage (enforced by CI) - **Test edge cases** - Consider error conditions and boundary cases - **Use meaningful test names** - Test names should describe what they're testing - **Keep tests isolated** - Tests should not depend on each other - **Mock external dependencies** - Use `pytest-mock` for mocking Prometheus API calls ### Test Structure ```python def test_feature_description(): """Test that feature does what it should.""" # Arrange - Set up test conditions # Act - Execute the functionality being tested # Assert - Verify the results ``` ## Pull Request Process 1. **Update your fork** with the latest changes from `main`: ```bash git fetch upstream git rebase upstream/main ``` 2. **Create a feature branch**: ```bash git checkout -b feature/your-feature-name ``` 3. **Make your changes** following the guidelines above 4. **Run tests locally**: ```bash pytest --cov=src --cov-report=term-missing ``` 5. **Push to your fork**: ```bash git push origin feature/your-feature-name ``` 6. **Create a Pull Request** with: - A clear title describing the change - A detailed description of what changed and why - References to related issues (e.g., "Fixes #123") - Screenshots or examples if applicable 7. **Address review feedback** - Be responsive to comments and suggestions 8. **Wait for CI/CD checks** - All automated checks must pass: - Tests must pass - Code coverage must meet minimum threshold (80%) - No security vulnerabilities detected ### Pull Request Checklist Before submitting, ensure your PR: - [ ] Follows the coding standards - [ ] Includes tests for new functionality - [ ] All tests pass locally - [ ] Maintains or improves code coverage - [ ] Updates documentation as needed - [ ] Has a clear and descriptive title - [ ] Includes a detailed description - [ ] References any related issues ## Release and Versioning **Important**: Releases and versioning are managed exclusively by repository administrators. Contributors should not: - Modify version numbers in `pyproject.toml` - Create release tags - Update changelog entries for releases The maintainers will handle: - Version bumping according to [Semantic Versioning](https://semver.org/) - Creating and publishing releases - Updating changelogs - Publishing to package registries - Building and pushing Docker images If you believe a release should be created, please open an issue to discuss it with the maintainers. ## Community and Support ### Getting Help - **Questions**: Use the [question template](https://github.com/pab1it0/prometheus-mcp-server/issues/new?template=question.yml) - **Discussions**: Check existing [issues](https://github.com/pab1it0/prometheus-mcp-server/issues) for similar questions - **Documentation**: Review the [README](README.md) for comprehensive documentation ### Recognition Contributors are recognized in: - Commit history and pull request comments - GitHub's contributor graph - Release notes for significant contributions Thank you for contributing to Prometheus MCP Server! Your efforts help make this project better for everyone.