Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
254 lines (199 loc) · 5.99 KB

CONTRIBUTING.md

File metadata and controls

254 lines (199 loc) · 5.99 KB
Raw

Contributing to NetOps Assistant

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

📋 Table of Contents

Code of Conduct

We are committed to providing a friendly, safe, and welcoming environment for all contributors. Please:

  • Be respectful and considerate
  • Accept constructive criticism gracefully
  • Focus on what is best for the community
  • Show empathy towards other community members

Getting Started

  1. Fork the repository to your GitHub account
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/netops-assistant.git
cd netops-assistant
  3. Set up development environment: 
    python -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate  # Windows

pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies
  4. Create a branch for your feature or fix: 
    git checkout -b feature/your-feature-name

Development Process

1. Check existing issues

Before starting work, check if there's an existing issue for your idea. If not, create one to discuss your proposal.

2. Types of Contributions

We welcome various types of contributions:

  • Bug fixes: Fix reported issues
  • Features: Add new functionality
  • Documentation: Improve or translate docs
  • Tests: Increase test coverage
  • Performance: Optimize existing code
  • Integrations: Add support for new platforms/vendors

3. Commit Messages

Follow conventional commits format:

type(scope): brief description

Detailed explanation if needed

Fixes #issue_number

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation
  • test: Tests
  • refactor: Code refactoring
  • perf: Performance improvement
  • chore: Maintenance

Example:

feat(telegram): add inline keyboard support for approvals

Added inline keyboards to approval notifications for better UX.
Admins can now approve/reject directly from Telegram.

Fixes #42

Pull Request Process

  1. Ensure your code works:

    # Run tests
pytest tests/

# Check code style
flake8 .
black . --check

# Validate configuration
python utils/config_validator.py

  2. Update documentation if you changed functionality

  3. Open a Pull Request with:

    • Clear title and description
    • Reference to related issue(s)
    • Screenshots/logs if applicable
    • Test results

  4. PR Review Process:

    • At least one maintainer review required
    • All CI checks must pass
    • Resolve all review comments
    • Keep PR focused and atomic

Testing

Running Tests

# All tests
pytest

# Specific module
pytest tests/test_workflow.py

# With coverage
pytest --cov=app --cov=services --cov=integrations

# Integration tests (requires services)
pytest tests/integration/ --integration

Writing Tests

  • Add unit tests for new functions
  • Include integration tests for new features
  • Test edge cases and error handling
  • Maintain >80% coverage for new code

Example test:

import pytest
from services.workflow import WorkflowService

@pytest.mark.asyncio
async def test_parameter_extraction():
    workflow = WorkflowService()
    result = await workflow.extract_parameters(
        "Configure port 5 on SW-01 in VLAN 100"
    )
    assert result['device_name'] == 'SW-01'
    assert result['interface'] == 'Gi0/5'
    assert result['vlan'] == 100

Code Style

We use Python 3.9+ with the following standards:

Formatting

  • Black for code formatting (line length: 100)
  • isort for import sorting
  • flake8 for linting

Run formatters:

black . --line-length 100
isort .
flake8 .

Best Practices

  • Type hints for function signatures
  • Docstrings for classes and public methods
  • Async/await for I/O operations
  • Context managers for resource handling
  • Proper error handling with custom exceptions

Example:

from typing import Dict, Optional
import asyncio

async def configure_interface(
    device: str, 
    interface: str, 
    vlan: int
) -> Dict[str, Any]:
    """
    Configure interface on network device.
    
    Args:
        device: Device hostname or IP
        interface: Interface name (e.g., 'Gi0/1')
        vlan: VLAN ID to configure
        
    Returns:
        Configuration result with status and job_id
        
    Raises:
        DeviceConnectionError: If device unreachable
        ValidationError: If parameters invalid
    """
    # Implementation
    pass

Documentation

Code Documentation

  • Add docstrings to all public functions/classes
  • Include type hints
  • Document exceptions
  • Provide usage examples

User Documentation

  • Update README.md for new features
  • Add examples to docs/EXAMPLES.md
  • Document configuration in docs/CONFIG.md
  • Include screenshots when relevant

API Documentation

For new integrations or APIs:

class NetBoxClient:
    """
    NetBox API client for device management.
    
    Example:
        >>> client = NetBoxClient(url="https://netbox.local", token="...")
        >>> device = await client.get_device("SW-01")
        >>> print(device.primary_ip)
    """

Attribution

This project is created and maintained by nimbo78:

By contributing, you agree that your contributions will be licensed under Apache License 2.0 with the attribution requirements specified in the LICENSE file.

Questions?

Feel free to:

  • Open an issue for questions
  • Contact maintainers via Telegram
  • Join discussions in existing issues

Thank you for contributing to NetOps Assistant! 🚀