💁Contributing

Thank you for your interest in contributing to ProxmoxMCP! This document provides guidelines and instructions for contributing to the project.

📚 Complete Documentation - For detailed guides and API reference

Table of Contents

• Code of Conduct

• Getting Started

• Development Environment

• Contribution Workflow

• Coding Standards

• Testing

• Documentation

• Issue and Pull Request Process

• Security Vulnerabilities

• Community

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please be respectful and considerate of others when contributing to the project.

Getting Started

1. Fork the repository on GitHub

2. Clone your fork locally

3. Set up the development environment

4. Create a new branch for your changes

5. Make your changes

6. Submit a pull request

Development Environment

Prerequisites

• Python 3.8 or higher

• Docker (for containerized development)

• Proxmox VE instance (for testing)

Setup

1. Clone the repository:

   git clone https://github.com/yourusername/ProxmoxMCP.git
   cd ProxmoxMCP

2. Set up git configuration for development:

   # Option 1: Copy project git configuration (recommended)
   cp example.gitconfig .git/config
   
   # Then update with your personal details
   git config user.name "Your Name"
   git config user.email "[e-mail]"
   
   # Option 2: Manual configuration
   git config user.name "Your Name"
   git config user.email "[e-mail]"
   git config core.editor "vscode"
   git config init.defaultBranch "main"
   git config pull.rebase true
   git config push.autoSetupRemote true

   The example.gitconfig includes development-friendly settings like:

   • Python/JSON/Dockerfile diff patterns

   • Useful aliases (git lg, git st, git sync)

   • Performance and security optimizations

3. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

4. Install development dependencies:

   pip install -e ".[dev]"

5. Install pre-commit hooks:

   pre-commit install

   This sets up automatic code quality checks that run before each commit. The hooks include:

   • Ruff formatting and linting

   • Type checking with mypy

   • Security scanning with bandit and safety

   • Markdown formatting validation

   Note: Pre-commit will automatically install required tools in isolated environments, so you don't need to install them globally.

6. Configure your Proxmox connection:

   cp proxmox-config/config.example.json proxmox-config/config.json
   # Edit config.json with your Proxmox credentials

Contribution Workflow

1. Check the issues for tasks to work on or create a new issue for your proposed change

2. Create a new branch from main:

   git checkout -b feature/your-feature-name

3. Make your changes

4. Add tests for your changes

5. Run the tests to ensure they pass:

   pytest

6. Update documentation as needed

7. Commit your changes with a descriptive commit message:

   git commit -m "Add feature: your feature description"

8. Push your branch to your fork:

   git push origin feature/your-feature-name

9. Create a pull request against the main branch of the original repository

Coding Standards

• Follow PEP 8 style guidelines

• Use type hints for function parameters and return values

• Write docstrings for all functions, classes, and modules

• Keep functions focused on a single responsibility

• Use meaningful variable and function names

• Add comments for complex logic

Code Formatting

We use the following tools for code formatting and linting:

• Ruff for code formatting and linting

• mypy for type checking

You can run these tools with:

ruff format src tests
ruff check src tests
mypy src tests

Testing

• Write unit tests for all new functionality

• Ensure all tests pass before submitting a pull request

• Aim for high test coverage of your code

• Include both positive and negative test cases

To run tests:

pytest

For coverage report:

pytest --cov=src

Documentation

• Update documentation for any changes to functionality

• Document all public APIs

• Include examples where appropriate

• Keep the README up to date

• Add docstrings to all functions, classes, and modules

Issue and Pull Request Process

Issues

• Use the appropriate issue template

• Provide clear and detailed information

• Include steps to reproduce for bugs

• Label issues appropriately

Pull Requests

• Reference the related issue in your pull request

• Provide a clear description of the changes

• Update documentation as needed

• Ensure all tests pass

• Request review from maintainers

Security Vulnerabilities

If you discover a security vulnerability, please do NOT open an issue. Instead, email [e-mail] with details. We take security issues seriously and will address them promptly.

Community

• Join our discussions for questions and community support

• Follow the project on GitHub to stay updated

• Share your success stories and use cases

Thank you for contributing to ProxmoxMCP!