Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
327 lines (243 loc) · 8.63 KB

CONTRIBUTING.md

File metadata and controls

327 lines (243 loc) · 8.63 KB

Contributing to Hier Config CLI

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

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.

How to Contribute

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

  • Clear title and description
  • Steps to reproduce the issue
  • Expected behavior vs actual behavior
  • Environment details (OS, Python version, tool version)
  • Sample configurations if applicable (sanitized of sensitive data)
  • Error messages or stack traces

Example:

**Bug**: Remediation fails on Juniper configs with curly braces

**To Reproduce**:
1. Run: `hier-config-cli remediation --platform junos --running-config r.conf --generated-config g.conf`
2. See error: ...

**Expected**: Should generate remediation commands
**Actual**: Raises ValueError

**Environment**: Python 3.11, hier-config-cli 0.2.0, Ubuntu 22.04

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

  • Use a clear and descriptive title
  • Provide detailed description of the proposed functionality
  • Explain why this enhancement would be useful
  • Provide examples of how it would be used
  • List alternatives you've considered

Pull Requests

  1. Fork the repository and create your branch from main
  2. Follow the development workflow (see below)
  3. Write tests for new functionality
  4. Ensure all tests pass and code quality checks succeed
  5. Update documentation as needed
  6. Submit the pull request with a clear description

Pull Request Process

  1. Update the README.md or relevant documentation with details of changes
  2. Add entries to CHANGELOG.md under "Unreleased" section
  3. Ensure the test suite passes (pytest)
  4. Ensure code quality checks pass (black, ruff, mypy)
  5. Update type hints for any new functions or modified signatures
  6. Request review from maintainers

Development Workflow

Setting Up Development Environment

# Clone your fork
git clone https://github.com/YOUR-USERNAME/hier-config-cli.git
cd hier-config-cli

# Add upstream remote
git remote add upstream https://github.com/netdevops/hier-config-cli.git

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Creating a Branch

# Update your fork
git fetch upstream
git checkout main
git merge upstream/main

# Create feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

Making Changes

  1. Write code following the project style guidelines
  2. Add tests for new functionality
  3. Run tests to ensure everything works
  4. Check code quality with linters and type checker
# Run tests
pytest

# Check test coverage
pytest --cov=hier_config_cli --cov-report=html

# Format code with black
black src/ tests/

# Lint with ruff
ruff check src/ tests/

# Type check with mypy
mypy src/

# Run all checks at once
black src/ tests/ && ruff check src/ tests/ && mypy src/ && pytest

Committing Changes

Write clear, concise commit messages following conventional commits:

# Feature
git commit -m "feat: add support for FortiOS platform"

# Bug fix
git commit -m "fix: correct Junos output formatting"

# Documentation
git commit -m "docs: update installation instructions"

# Tests
git commit -m "test: add error handling tests"

# Refactor
git commit -m "refactor: consolidate duplicate command code"

Submitting Pull Request

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

# Create pull request on GitHub
# Include:
# - Clear description of changes
# - Reference to related issues
# - Screenshots if applicable
# - Checklist of completed items

Coding Standards

Python Style Guide

  • Follow PEP 8 style guide
  • Use Black for code formatting (line length: 100)
  • Use Ruff for linting
  • Use mypy for type checking

Code Organization

  • Keep functions focused and single-purpose
  • Use descriptive variable and function names
  • Add docstrings to all public functions and classes
  • Include type hints for all function signatures
  • Avoid code duplication (DRY principle)

Documentation Standards

Docstrings

Use Google-style docstrings:

def process_configs(
    platform_str: str,
    running_config_path: str,
    generated_config_path: str,
    operation: str,
) -> tuple[HConfig, Platform]:
    """Process configuration files and return the result.

    Args:
        platform_str: Platform name string
        running_config_path: Path to running configuration
        generated_config_path: Path to generated configuration
        operation: Operation type (remediation, rollback, future)

    Returns:
        Tuple of (result HConfig, Platform enum)

    Raises:
        click.ClickException: If processing fails
    """

Type Hints

Always include type hints:

from typing import Optional
from pathlib import Path

def save_output(content: str, filepath: Optional[Path] = None) -> None:
    """Save output to file."""
    if filepath:
        filepath.write_text(content)

Testing Standards

  • Write tests for all new functionality
  • Maintain or improve code coverage
  • Test both happy paths and error cases
  • Use descriptive test names
  • Include docstrings in test functions
def test_remediation_with_invalid_platform(
    mock_running_config: str,
    mock_generated_config: str
) -> None:
    """Test that remediation fails gracefully with invalid platform."""
    runner = CliRunner()
    result = runner.invoke(
        cli,
        [
            "remediation",
            "--platform", "invalid_platform",
            "--running-config", mock_running_config,
            "--generated-config", mock_generated_config,
        ],
    )
    assert result.exit_code != 0
    assert "Unknown platform" in result.output

Project Structure

hier-config-cli/
├── src/
│   └── hier_config_cli/
│       ├── __main__.py      # Main CLI code
│       └── py.typed         # Type hints marker
├── tests/
│   └── test_cli.py          # Test suite
├── examples/                # Example configurations
│   ├── cisco_ios_running.conf
│   ├── cisco_ios_intended.conf
│   └── README.md
├── .github/
│   └── workflows/           # CI/CD workflows
├── pyproject.toml           # Project configuration
├── README.md                # Main documentation
├── CONTRIBUTING.md          # This file
├── CHANGELOG.md             # Version history
├── SECURITY.md              # Security policy
└── LICENSE                  # License file

Adding New Platforms

To add support for a new network platform:

  1. Add the platform to PLATFORM_MAP in src/hier_config_cli/__main__.py
  2. Ensure proper output formatting in get_output_text() function
  3. Add test cases for the new platform
  4. Update documentation (README.md, examples)
  5. Add example configuration files if available

Example:

PLATFORM_MAP = {
    # ... existing platforms ...
    "new_platform": Platform.NEW_PLATFORM,
}

Adding New Features

When adding new features:

  1. Discuss first by opening an issue to get feedback
  2. Design carefully considering backwards compatibility
  3. Write tests covering new functionality
  4. Document thoroughly in code and README
  5. Update CHANGELOG with your changes

Release Process

Maintainers handle releases. The process:

  1. Update version in pyproject.toml and src/hier_config_cli/__main__.py
  2. Update CHANGELOG.md with release notes
  3. Create git tag for release
  4. GitHub Actions automatically publishes to PyPI

Getting Help

Recognition

Contributors will be recognized in:

  • GitHub contributors list
  • CHANGELOG.md for significant contributions
  • Project README (for major features)

License

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

Thank you for contributing to Hier Config CLI! Your efforts help make network automation better for everyone.