Link to this sectionDevelopment Workflow 💻#

This guide covers how Ultralytics employees and contributors plan, implement, review, test, and merge changes across Ultralytics projects, including YOLO and related repositories.

The workflow is intentionally lightweight: keep changes focused, make review easy, run the right checks, and leave enough context for teammates to understand the decision later.

Link to this sectionCode of Conduct 🤝#

All contributors must follow the Code of Conduct. Respect, clarity, and professionalism are expected in issues, PRs, reviews, internal discussions, and public community spaces. For public contribution requirements, see the Official Contributing Guide.

Link to this sectionCollaboration Cadence 🛰️#

• Anchor Days (Tue/Wed/Thu): Use these days for code reviews, design discussions, debugging sessions, and decisions that benefit from synchronous collaboration.
• Mon/Fri: Favor deep work, written updates, PR preparation, and async review. Move critical blockers to the next Anchor Day when synchronous alignment is needed.
• Standups & Reviews: Timebox standups to 15 minutes. Schedule design and architecture reviews on Anchor Days when possible.
• Decision Records: Capture important decisions in PR descriptions, issues, docs, or runbooks so context does not disappear in chat.

Link to this sectionScope and Ownership 🧭#

This workflow applies to Ultralytics engineering work across product, Ultralytics Platform, YOLO, infrastructure, documentation, automation, and security-sensitive systems. Individual repositories may add stricter requirements, but they should not weaken the baseline expectations in this page.

Every work item should have a clear owner:

• Author: Implements the change, keeps the PR current, and provides validation evidence.
• Reviewer: Confirms correctness, maintainability, risk, and documentation impact.
• Domain owner: Reviews changes affecting a specialized area such as model behavior, infrastructure, security, privacy, licensing, or customer-facing workflows.
• Triage owner: Assigns incoming issues, incidents, vulnerability reports, and maintenance work to the right owner.

Link to this sectionPull Request Process 🔄#

flowchart TD
    A[Fork or Sync 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

Link to this section1. Fork or Sync the Repository#

External contributors should fork the relevant Ultralytics repository, such as ultralytics/ultralytics, to their GitHub account.

Employees with write access should sync main before branching:

# External contributors
git clone https://github.com/YOUR_USERNAME/ultralytics.git
cd ultralytics

# Employees with write access
git checkout main
git pull origin main

Link to this section2. Create a Feature Branch#

Create a branch with a clear, descriptive name that reflects the work:

git checkout -b fix-issue-123

Link to this section3. Make Your Changes#

Link to this section4. Test Your Changes#

pytest tests/

Learn more: Testing Requirements, Model Validation, CI Workflows

Link to this section5. Commit Your Changes#

Commit with concise, descriptive messages:

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

Link to this section6. Create Pull Request#

Submit PR from your branch to main:

Link to this section7. Sign the CLA#

After submitting your PR, add this comment:

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

Link to this section8. Address Review Feedback#

Respond to reviewer comments, push updates, and keep the PR description current if the scope changes. Resolve all blocking feedback before requesting re-review.

Link to this sectionGoogle-Style Docstrings 📝#

Public functions and classes should use Google-style docstrings where the repository expects them. Keep docstrings accurate, concise, and useful for future maintainers.

Link to this sectionStandard 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

Link to this sectionNamed 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

Link to this sectionMultiple 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: When a function returns multiple values, document each return value separately instead of hiding important details inside a generic tuple description.

✅ 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.

Link to this sectionWith 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

Link to this sectionSingle-Line Docstrings#

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

Link to this sectionCode Standards 📐#

Link to this sectionPython Style#

Link to this sectionCode Quality#

Link to this sectionBest Practices#

Link to this sectionSecurity Frameworks 🛡️#

Ultralytics engineering practices should align with recognized secure development guidance, including OWASP Secure Software Development Lifecycle, OWASP Application Security Verification Standard, and OWASP Top 10. Teams should use these references when planning secure design, review, testing, and remediation work.

Link to this sectionAsset Management 🗂️#

Engineering assets should have a clear owner and a reliable source of truth. This includes repositories, services, cloud resources, CI/CD runners, domains, datasets, model artifacts, API keys, secrets, deployment environments, and third-party integrations.

When creating, changing, or retiring an asset:

• Assign an owner and maintenance contact.
• Record purpose, environment, access requirements, and lifecycle state.
• Review access and least-privilege permissions.
• Keep secrets and credentials out of code, logs, screenshots, and documentation.
• Update runbooks, diagrams, inventories, or documentation when ownership or behavior changes.
• Retire unused assets to reduce security, cost, and maintenance risk.

Link to this sectionDocumentation Review 📝#

Documentation should stay aligned with current roles, ownership, workflows, and security expectations. When a process changes, update the relevant handbook page, public docs, runbook, or README in the same PR where practical.

Documentation reviewers should check:

• Role names, ownership, and escalation paths are current.
• Security, compliance, and licensing language matches current policy.
• Links, diagrams, commands, and screenshots still reflect the product or workflow.
• New or changed processes include a clear owner and review cadence.
• Public documentation does not expose internal-only information, secrets, customer data, or sensitive operational details.

Link to this sectionTesting Requirements ✅#

All PRs should include validation that matches the risk of the change:

pytest tests/

# When coverage is relevant
pytest --cov=ultralytics tests/

For model behavior changes, include the dataset, model, command, hardware, and before/after metrics where practical. For documentation changes, build the docs locally and include screenshots or preview links for layout changes. See CI/Testing for CI details.

Link to this sectionCode Review Guidelines 👀#

Link to this sectionFor Contributors#

• Keep PRs focused on one feature, fix, or documentation update.
• Explain the problem, solution, validation, and risks.
• Respond promptly to feedback.
• Treat review as part of the work, not a personal judgment.
• Update the PR description if scope changes.

Link to this sectionFor Reviewers#

• Review within one to two business days or redirect quickly.
• Check tests and validation evidence for new behavior.
• Review documentation updates for user-visible changes.
• Evaluate performance, compatibility, security, privacy, and maintainability impact.
• Verify relevant CI checks pass.
• Provide constructive, specific feedback.
• Distinguish blocking issues from suggestions.

Link to this sectionGit Best Practices 🌳#

Link to this sectionCommits#

• Use present tense: "Add feature" not "Added feature".
• Write clear, descriptive messages.
• Keep commits focused and logical.
• Avoid mixing formatting-only churn with behavior changes.

Link to this sectionBranches#

• Pull latest main before creating branches.
• Rebase or merge main before final submission when the branch has drifted.
• Delete branches after merge.

Link to this sectionReporting 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.

Link to this sectionLicense 📜#

Many Ultralytics repositories use the AGPL-3.0 license. If you use AGPL-licensed Ultralytics code in your project, your project may also need to be open-sourced under AGPL-3.0. If you need closed-source or commercial use, review the Enterprise License.

Link to this sectionResources 📚#

• Official Contributing Guide - Complete contribution guidelines
• CI/Testing - Continuous integration details
• Documentation - Writing and maintaining docs
• Code of Conduct - Community standards
• CLA Instructions - Contributor License Agreement guidance
• Minimum Reproducible Example - Bug report examples
• Ultralytics Blog - Latest updates and tutorials
• Community Events - Webinars and conferences