Contributing to RDSAI CLI

December 27, 2025 · View on GitHub

Thank you for your interest in contributing to RDSAI CLI! This document provides guidelines and instructions for contributing.

🚀 Getting Started

Prerequisites

  • Python 3.13+
  • uv (recommended) or pip
  • Git
  • MySQL instance (for testing database features)

Development Setup

# Clone the repository
git clone https://github.com/aliyun/rdsai-cli.git
cd rdsai-cli

# Install dependencies with uv (recommended)
uv sync --extra dev

# Or with pip (use virtual environment recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run the CLI
uv run rdsai
# or if using pip with venv
python -m cli

Running Tests

You can use the convenience script or run pytest directly:

# Using the convenience script (recommended)
./dev/pytest.sh

# Or run pytest directly
uv run pytest

# Run specific test file
uv run pytest tests/loop/test_runtime.py

# Run tests with verbose output
uv run pytest -v

# Run tests matching a pattern
uv run pytest -k "test_runtime"

# Run with coverage (requires pytest-cov)
uv run pytest --cov=. --cov-report=html

Note: This project uses pytest-asyncio for async tests. Make sure async test functions are properly decorated.

Code Quality

We use Ruff for linting and formatting:

# Using the convenience script (recommended)
# Auto-fix linting and formatting issues
./dev/code-style.sh

# Check only (without fixing)
./dev/code-style.sh --check

# Or run commands directly
# Check for linting errors (without fixing)
uv run ruff check .

# Auto-fix linting errors
uv run ruff check --fix .

# Check code formatting (without reformatting)
uv run ruff format --check .

# Auto-format code
uv run ruff format .

# Run all checks at once
uv run ruff check . && uv run ruff format --check . && uv run pytest

CI/CD: Our GitHub Actions workflows automatically run these checks on every push and PR:

  • Lint workflow (lint.yml): Runs ruff check and ruff format --check
  • Test workflow (python-package.yml): Runs pytest on Python 3.13

📝 Code Style

General Guidelines

  • Follow PEP 8 conventions
  • Use type hints for all function signatures
  • Write docstrings for public functions and classes
  • Keep line length under 120 characters
  • Use meaningful variable and function names

Code Formatting

  • Ruff handles all formatting automatically
  • Run ruff format . before committing
  • The formatter enforces consistent style across the codebase

🔄 Pull Request Process

Before Submitting

  1. Create an issue first (optional but recommended) — Discuss the change you want to make
  2. Fork the repository — Create your own copy
  3. Create a feature branch — git checkout -b feature/your-feature-name or git checkout -b fix/your-bug-name
  4. Make your changes — Follow the code style guidelines
  5. Write tests — Ensure your changes are covered with appropriate tests
  6. Run all checks locally — Ensure everything passes before submitting: 
    # Fix linting and formatting issues
./dev/code-style.sh

# Run tests
./dev/pytest.sh

Submitting

  1. Commit your changes — Write clear, descriptive commit messages

    git add .
git commit -m "feat: add new feature description"
# or
git commit -m "fix: resolve bug description"

  2. Push your branch to your fork

    git push origin feature/your-feature-name

  3. Open a Pull Request against the main branch

    • Fill out the PR description template
    • Reference related issues if applicable
    • Add screenshots or examples if relevant

  4. Wait for review — Address feedback promptly

PR Guidelines

  • Keep PRs focused — One feature/fix per PR
  • Write clear commit messages — Use conventional commit format:
    • feat: for new features
    • fix: for bug fixes
    • docs: for documentation changes
    • refactor: for code refactoring
    • test: for test additions/changes
    • chore: for maintenance tasks
  • Update documentation — If you add features or change behavior
  • Add tests — New features should include tests
  • Ensure CI passes — All GitHub Actions checks must pass
  • Keep PRs small — Easier to review and merge

Pre-commit Checklist

Before submitting your PR, ensure:

  • Code follows style guidelines
  • All type hints are present and correct
  • Tests pass locally (./dev/pytest.sh)
  • Code style checks pass (./dev/code-style.sh --check)
  • Documentation is updated if needed
  • Commit messages are clear and descriptive

🐛 Reporting Issues

Bug Reports

When reporting a bug, please include:

  • RDSAI CLI version — rdsai --version
  • Python version — python --version or uv python list
  • Operating system — OS name and version
  • Steps to reproduce — Clear, step-by-step instructions
  • Expected behavior — What you expected to happen
  • Actual behavior — What actually happened
  • Error messages or logs — Full error traceback if available
  • Configuration — Relevant config files or settings (redact sensitive info)
  • Database version — MySQL version if relevant

Feature Requests

When requesting a feature, please include:

  • Clear description — What the feature should do
  • Use case — Why is this needed? What problem does it solve?
  • Possible implementation approach — Optional, but helpful
  • Alternatives considered — What other solutions did you consider?

Issue Templates

Use GitHub issue templates when available:

  • Bug report template
  • Feature request template

💬 Communication

  • GitHub Issues — Bug reports, feature requests, questions
  • GitHub Discussions — General discussion, ideas, Q&A
  • Pull Requests — Code contributions with review and discussion

📜 License

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

Thank you for contributing to RDSAI CLI! 🎉

Your contributions help make this project better for everyone. If you have questions or need help, don't hesitate to open an issue or start a discussion.