​

Contributing to DZDK CLI

​

Getting Started

​

Prerequisites

• Python 3.8 or higher
• Git
• pip (Python package manager)

​

Fork and Clone

1. Fork the Repository Visit the DZDK CLI repository and click the “Fork” button in the top-right corner.
2. Clone Your Fork
   Copy

   git clone https://github.com/YOUR_USERNAME/dzdk-cli.git
   cd dzdk-cli
   
3. Add Upstream Remote
   Copy

   git remote add upstream https://github.com/Dzaleka-Connect/dzdk-cli.git
   

​

Development Environment Setup

​

1. Create a Virtual Environment

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

​

2. Install Dependencies

# Install production dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements-dev.txt

• click>=8.0.0 - Command-line interface framework
• requests>=2.26.0 - HTTP library for API calls
• rich>=10.0.0 - Rich terminal output formatting
• pyyaml>=6.0 - YAML configuration file support
• pandas>=2.0.0 - Data manipulation and export
• tabulate>=0.9.0 - Table formatting
• prompt-toolkit>=3.0.0 - Interactive shell features
• python-dateutil>=2.8.2 - Date/time parsing

• pytest==8.0.0 - Testing framework
• pytest-cov==4.1.0 - Code coverage reporting
• pytest-mock==3.12.0 - Mocking support for tests
• black==24.3.0 - Code formatter
• flake8==7.0.0 - Code linter
• mypy==1.8.0 - Static type checker

​

3. Install in Editable Mode

pip install -e .

​

4. Verify Installation

dzdk --help

​

Code Style Guidelines

​

Python Code Style

​

Formatting

• Use Black for automatic code formatting:
  Copy

  black dzdk.py
  black tests/
  
• Line length: Maximum 100 characters (Black default)
• Indentation: 4 spaces (no tabs)
• String quotes: Double quotes for docstrings, either for regular strings

​

Linting

• Run flake8 to check for style issues:
  Copy

  flake8 dzdk.py
  flake8 tests/
  

​

Type Checking

• Use type hints where possible:
  Copy

  def format_response(response: requests.Response) -> Dict[str, Any]:
      """Format API response with proper error handling."""
      # implementation
  
• Run mypy for type checking:
  Copy

  mypy dzdk.py
  

​

Documentation

• Use clear, descriptive docstrings for all functions and classes:
  Copy

  def check_endpoint(endpoint: str) -> Dict[str, Any]:
      """Check a single API endpoint.
      
      Args:
          endpoint: The API endpoint path to check
          
      Returns:
          Dictionary containing endpoint status and metrics
      """
  
• Add inline comments for complex logic
• Update README.md when adding new features or commands

​

Rich Output Guidelines

• Use Rich library for consistent terminal output:
  • console.print() for formatted output
  • create_header() for section headers
  • create_info_panel() for information boxes
  • create_table() for tabular data
• Follow the existing color scheme:
  • Info: cyan
  • Warning: yellow
  • Danger/Error: red
  • Success: green
  • Title: bold cyan
  • Highlight: bold yellow

​

Error Handling

try:
    response = requests.get(url, timeout=TIMEOUT)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    console.print(f"[red]HTTP Error: {str(e)}[/red]")
    sys.exit(1)
except requests.exceptions.RequestException as e:
    console.print(f"[red]Request Error: {str(e)}[/red]")
    sys.exit(1)
except json.JSONDecodeError:
    console.print("[red]Invalid JSON response[/red]")
    sys.exit(1)

​

Making Changes

​

Create a Feature Branch

git checkout -b feature/your-feature-name

• feature/add-export-command - for new features
• fix/api-timeout-handling - for bug fixes
• docs/update-readme - for documentation updates
• refactor/improve-error-handling - for refactoring

​

Development Workflow

1. Make your changes in the appropriate files
2. Format your code with Black:
   Copy

   black dzdk.py tests/
   
3. Check for linting issues:
   Copy

   flake8 dzdk.py tests/
   
4. Run tests to ensure nothing is broken:
   Copy

   pytest
   
5. Add tests for new functionality (see Testing Guide)
6. Update documentation if needed:
   • Update README.md with new commands
   • Add docstrings to new functions
   • Update help text for CLI commands

​

Commit Guidelines

• Write clear, descriptive commit messages
• Use the present tense (“Add feature” not “Added feature”)
• Reference issues when applicable

Add export command for CSV and markdown reports

Fixes #123

Fix timeout handling in API health checks

- Add proper timeout exception handling
- Improve error messages for connection issues
- Update tests to cover timeout scenarios

​

Pull Request Process

​

Before Submitting

1. Update your branch with the latest changes:
   Copy

   git fetch upstream
   git rebase upstream/main
   
2. Run the full test suite:
   Copy

   pytest --cov=dzdk tests/
   
3. Verify code quality:
   Copy

   black --check dzdk.py tests/
   flake8 dzdk.py tests/
   mypy dzdk.py
   
4. Test manually by running the CLI with your changes:
   Copy

   dzdk health
   dzdk services list
   # Test all affected commands
   

​

Submitting Your PR

1. Push your changes:
   Copy

   git push origin feature/your-feature-name
   
2. Create a Pull Request on GitHub
3. Fill out the PR template with:
   • Clear description of changes
   • Motivation and context
   • Screenshots (if UI changes)
   • Testing steps
   • Related issues
4. Address review feedback promptly

​

PR Requirements

• ✅ All tests pass
• ✅ Code is formatted with Black
• ✅ No linting errors from flake8
• ✅ New tests added for new features
• ✅ Documentation updated (if applicable)
• ✅ Commit messages are clear and descriptive

​

Adding New Features

​

1. Follow Existing Structure

• Use Click decorators for commands and options
• Group related commands under command groups
• Example structure:
  Copy

  @cli.group()
  def myfeature():
      """Manage my feature"""
      pass
  
  @myfeature.command("list")
  @click.option('--filter', help='Filter results')
  def list_items(filter):
      """List all items"""
      # implementation
  

​

2. Add Error Handling

• Use try-except blocks for API calls
• Provide informative error messages
• Exit with appropriate status codes

​

3. Include Progress Indicators

• Use Rich Progress for long operations:
  Copy

  with console.status("[bold green]Fetching data..."):
      # long operation
  

​

4. Add Documentation

• Update README.md with new command examples
• Add comprehensive docstrings
• Update help text for discoverability

​

5. Write Tests

​

Code Review Process

1. Automated checks run on your PR:
   • Test suite execution
   • Code quality checks
   • Coverage reports
2. Manual review by maintainers:
   • Code quality and style
   • Functionality and correctness
   • Documentation completeness
   • Test coverage
3. Approval and merge:
   • At least one maintainer approval required
   • All checks must pass
   • Branch must be up-to-date with main

​

Getting Help

• Open an issue on GitHub for bugs or feature requests
• Start a discussion for questions or ideas
• Join our community at Dzaleka Connect
• Email us at contact@mail.dzaleka.com

​

Code of Conduct

• Be respectful and inclusive
• Focus on constructive feedback
• Help others learn and grow
• Follow project guidelines