Contributing to kibana-py¶

Thank you for your interest in contributing to kibana-py! This guide provides everything you need to know to contribute effectively.

Code of Conduct¶

This project adopts the Contributor Covenant v2.1 as its code of conduct. By participating, you are expected to uphold these standards.

Getting Started¶

Prerequisites¶

Python 3.10 or higher
Git
A running Kibana instance for integration tests (optional but recommended)

Finding Issues to Work On¶

Check the issue tracker for open issues
Look for issues labeled good first issue or help wanted
Feel free to ask questions on issues before starting work

Development Setup¶

1. Fork and Clone¶

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/kibana-py.git
cd kibana-py

# Add upstream remote
git remote add upstream https://github.com/pedro-angel/kibana-py.git

2. Create Virtual Environment¶

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate

# On Windows:
.venv\Scripts\activate

3. Install Development Dependencies¶

# Install the package in editable mode with development dependencies
pip install -e ".[dev]"

# Verify installation
python -c "import kibana; print(kibana.__version__)"

4. Set Up Local Kibana (Optional)¶

For integration testing, you can use the provided local Elastic Stack:

./local-stack.sh -o start

# The script will create a .env file with credentials
# Integration tests will automatically use these credentials

# To stop:
./local-stack.sh -o stop

Development Workflow¶

1. Create a Branch¶

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name

2. Make Changes¶

Write your code following the project’s coding standards
Add or update tests as needed
Update documentation if you’re changing functionality
Keep commits focused and atomic

3. Run Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/unit/test_base_client.py

# Run with coverage
pytest --cov=kibana --cov-report=term-missing

See Testing Guide for detailed testing guidelines.

4. Run Required Local Checks¶

# Mandatory before opening a PR
make pre-commit

# Strongly recommended before opening a PR (CI parity)
make check

What each target does:

make pre-commit: required. Runs all pre-commit hooks on all files (includes formatting and Ruff fixes/checks).
make fix: optional convenience target. Applies auto-fixes via pinned pre-commit formatter/lint hooks (isort, black, ruff –fix).
make lint: mypy type-check only.
make check: full local CI gate (pre-commit + mypy + pip-audit + bandit + unit tests).

If you use nox, these are still valid alternatives for broader local workflows:

nox -s format
nox -s lint

5. Commit Changes¶

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add feature: description of your changes"

Follow these commit message guidelines:

Use present tense (“Add feature” not “Added feature”)
Use imperative mood (“Move cursor to…” not “Moves cursor to…”)
Limit first line to 72 characters
Reference issues and pull requests when relevant

6. Push and Create Pull Request¶

# Push to your fork
git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Quality Standards¶

Code Style¶

Black for code formatting (line length: 88)
isort for import sorting (black profile)
Type hints required for all public APIs
Docstrings required for all public functions and classes

Linting¶

Ruff for linting (replaces flake8, pylint, etc.)
Mypy for static type checking (strict mode)
Pyright for additional type checking

Running Quality Checks¶

# Mandatory
make pre-commit

# Optional convenience
make fix
make lint

# Full CI parity
make check

Pre-commit Hooks¶

Installing hooks is strongly recommended so required checks run before each commit:

pip install pre-commit
pre-commit install

Documentation Guidelines¶

Docstring Format¶

Use Google-style docstrings for consistency with the documentation system:

def create(
    self,
    *,
    name: str,
    connector_type_id: str,
    config: dict[str, Any],
    secrets: dict[str, Any] | None = None,
) -> ObjectApiResponse[dict[str, Any]]:
    """Create a new action connector.

    Creates a connector (action) in Kibana that can be used for alerting
    and automation workflows.

    Args:
        name: Display name for the connector.
        connector_type_id: Type of connector (e.g., ".index", ".webhook").
        config: Connector-specific configuration.
        secrets: Sensitive connector configuration (optional).

    Returns:
        API response containing the created connector details including
        the connector ID.

    Raises:
        ConflictError: If a connector with the same name already exists.
        BadRequestError: If the configuration is invalid.

    Example:
        >>> client = Kibana("http://localhost:5601")
        >>> connector = client.actions.create(
        ...     name="My Webhook",
        ...     connector_type_id=".webhook",
        ...     config={"url": "https://example.com/webhook"}
        ... )
        >>> print(connector.body["id"])
    """

Documentation Requirements¶

When adding or changing functionality:

Update docstrings in the code with comprehensive descriptions
Update user guide if adding new features or changing behavior
Add examples to demonstrate usage patterns
Update API reference if changing method signatures
Update CHANGELOG.md with your changes

Building Documentation Locally¶

# Install documentation dependencies
pip install -r docs/requirements.txt

# Build HTML documentation
cd docs
make html

# View documentation
open build/html/index.html  # macOS
# or
xdg-open build/html/index.html  # Linux

Submitting Changes¶

Pull Request Process¶

Update your branch with the latest upstream changes:
```
git fetch upstream
git rebase upstream/main
```
Ensure all tests pass and code quality checks succeed
Create a pull request with:
- Clear title describing the change
- Description of what changed and why
- Reference to related issues
- Screenshots/examples if applicable
Respond to review feedback promptly
Squash commits if requested before merging

Pull Request Checklist¶

[ ] Tests pass locally (pytest)
[ ] Code is formatted (black, isort)
[ ] Code passes linting (ruff, mypy)
[ ] Documentation is updated
[ ] Docstrings follow Google style
[ ] CHANGELOG.md is updated
[ ] Commit messages are clear and descriptive
[ ] Branch is up to date with main

Review Process¶

What to Expect¶

Initial review within 1-2 business days
Constructive feedback on code, tests, and documentation
Requests for changes or clarifications
Approval once all feedback is addressed

Review Guidelines¶

When reviewing others’ contributions:

Be respectful and constructive
Focus on code quality, not personal preferences
Suggest improvements with examples
Approve when standards are met

Getting Help¶

Questions: Open a discussion on GitHub
Bugs: Open an issue with reproduction steps
Features: Open an issue to discuss before implementing
Chat: Join the Elastic community Slack

Additional Resources¶

Testing Guide - Comprehensive testing guide
Adding Space Support to New API Clients - Adding space support to new clients
Architecture - Project architecture overview
Python Packaging Guide
pytest Documentation
Type Hints (PEP 484)
Kibana API Documentation

License¶

By contributing to kibana-py, you agree that your contributions will be licensed under the Apache License 2.0.

Thank you for contributing to kibana-py! 🎉