Development Workflow 💻

This guide covers the development process for contributing to Ultralytics projects, including YOLO11 and related repositories.

Code of Conduct 🤝

All contributors must adhere to our Code of Conduct. Respect, kindness, and professionalism are at the heart of our community. For detailed contribution guidelines, see the Official Contributing Guide.

Pull Request Process 🔄

flowchart TD
    A[Fork Repository] --> B[Create Feature Branch]
    B --> C[Make Changes]
    C --> D[Run Tests Locally]
    D --> E[Commit Changes]
    E --> F[Create Pull Request]
    F --> G[Sign CLA]
    G --> H{Review}
    H -->|Changes Requested| I[Address Feedback]
    I --> H
    H -->|Approved| J[Merge!]

    style A fill:#e1f5ff
    style J fill:#d4edda
    style G fill:#fff3cd

1. Fork the Repository

Fork the relevant Ultralytics repository (e.g., ultralytics/ultralytics) to your GitHub account.

# Clone your fork
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

2. Create Feature Branch

Create a branch with a clear, descriptive name:

git checkout -b fix-issue-123

3. Make Your Changes

4. Test Your Changes

pytest tests/

Learn more: Testing Requirements, Model Validation, CI Workflows

5. Commit Your Changes

Commit with concise, descriptive messages:

git commit -m "Fix #123: Corrected calculation error"

!!! tip "Commit Message Best Practices" - Use present tense ("Add feature" not "Added feature") - Reference issue numbers when applicable - Keep subject line under 72 characters

6. Create Pull Request

Submit PR from your branch to main:

7. Sign the CLA

After submitting your PR, add this comment:

I have read the CLA Document and I sign the CLA

The CLA bot will guide you through the process. For more details on licensing, see our contributing guide.

8. Address Review Feedback

Respond to reviewer comments and push updates.

Google-Style Docstrings 📝

All functions and classes require Google-style docstrings with types in parentheses.

Standard Function

def example_function(arg1, arg2=4):
    """Example function demonstrating Google-style docstrings.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
        >>> example_function(1, 2)  # False
    """
    return arg1 == arg2

Named Returns

def example_function(arg1, arg2=4):
    """Example function with named return.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(4, 4)  # True
    """
    equals = arg1 == arg2
    return equals

Multiple Returns

def example_function(arg1, arg2=4):
    """Example function with multiple returns.

    Args:
        arg1 (int): The first argument.
        arg2 (int): The second argument.

    Returns:
        equals (bool): True if arguments are equal, False otherwise.
        added (int): Sum of both input arguments.

    Examples:
        >>> equals, added = example_function(2, 2)  # True, 4
    """
    equals = arg1 == arg2
    added = arg1 + arg2
    return equals, added

Important: Document each return value separately, not as a tuple.

✅ Good:

Returns:
    (np.ndarray): Predicted masks with shape HxWxN.
    (list): Confidence scores for each instance.

❌ Bad:

Returns:
    (tuple): Tuple containing:
        - (np.ndarray): Predicted masks with shape HxWxN.
        - (list): Confidence scores for each instance.

With Type Hints

def example_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with type hints.

    Args:
        arg1: The first argument.
        arg2: The second argument.

    Returns:
        True if arguments are equal, False otherwise.

    Examples:
        >>> example_function(1, 1)  # True
    """
    return arg1 == arg2

Single-Line Docstrings

def example_small_function(arg1: int, arg2: int = 4) -> bool:
    """Example function with a single-line docstring."""
    return arg1 == arg2

Code Standards 📐

Python Style

Code Quality

Best Practices

Testing Requirements ✅

All PRs must pass CI tests:

# Run tests locally
pytest tests/

# With coverage
pytest --cov=ultralytics tests/

See CI/Testing for CI details.

Code Review Guidelines 👀

For Contributors

• Keep PRs focused on single feature/fix
• Respond promptly to feedback
• Don't take feedback personally
• Update PR description if scope changes

For Reviewers

• Review within 1-2 business days
• Check unit tests for new features
• Review documentation updates
• Evaluate performance impact
• Verify CI tests pass
• Provide constructive, specific feedback
• Recognize author's effort

Git Best Practices 🌳

Commits

• Present tense: "Add feature" not "Added feature"
• Clear, descriptive messages
• Focused, logical commits

Branches

• Pull latest main before creating branches
• Rebase on main before final submission
• Delete branches after merge

Reporting Bugs 🐞

Report bugs via GitHub Issues:

1. Check existing issues first
2. Provide Minimum Reproducible Example
3. Describe environment: OS, Python version, library versions, hardware (use yolo checks for diagnostics)
4. Explain expected vs actual behavior with error messages

For common issues and solutions, see our troubleshooting guide.

License 📜

Ultralytics uses AGPL-3.0. If using Ultralytics code in your project, your entire project must be open-sourced under AGPL-3.0. If you prefer not to open-source, obtain an Enterprise License.

Resources 📚

• Official Contributing Guide - Complete contribution guidelines
• CI/Testing - Continuous integration details
• Documentation - Writing and maintaining docs
• Code of Conduct - Community standards
• Ultralytics Blog - Latest updates and tutorials
• Community Events - Webinars and conferences

📅 Created 3 days ago ✏️ Updated 2 days ago