How to Report a Bug in Switchyard: The Complete Contributor Guide

To report a bug in Switchyard, open a GitHub Issue using the Bug report template, provide a minimal reproducible example under 30 lines, and include your environment details and full traceback logs.

If you encounter unexpected behavior in the NVIDIA-NeMo/Switchyard repository, submitting a detailed bug report helps maintainers diagnose and resolve issues efficiently. Understanding how to report a bug in Switchyard ensures your issue receives prompt attention and actionable feedback. This guide walks through the exact process defined in the project's .github/ISSUE_TEMPLATE/bug_report.md and CONTRIBUTING.md files.

Search Existing Issues Before Reporting

Before creating a new issue, search the existing Switchyard issue tracker to confirm the problem has not already been reported. Duplicate reports fragment discussion and slow down the triage process. If you find a related issue, add your reproduction details or environment information to the existing thread rather than opening a duplicate.

Open a Bug Report Using the GitHub Template

Switchyard uses GitHub Issues exclusively for bug tracking. Navigate to the repository issue tracker at https://github.com/NVIDIA-NeMo/Switchyard/issues and click “New issue.” Select the Bug report template to ensure you include all required fields.

The template in .github/ISSUE_TEMPLATE/bug_report.md requires the following information:

• Title – A concise summary of the problem that helps maintainers identify the issue category at a glance.
• Description – Explain what you expected to happen versus what actually occurred.
• Steps to reproduce – A minimal, reproducible snippet or command line that triggers the bug consistently.
• Environment – Your operating system, Python version, and Switchyard version obtained via pip show switchyard.
• Logs / Tracebacks – The full error output and relevant log files. Never paste API keys or secrets.
• Additional context – Links to related PRs, external documentation, or other issues that provide background.

Create a Minimal Reproducible Example

A minimal reproducible example (MRE) isolates the failure in the fewest lines of code possible, ideally fewer than 30 lines. This eliminates variables unrelated to the bug and allows maintainers to verify the issue quickly. For Python-side bugs, focus on the entry points in switchyard/libsy/algorithms.py, which serves as a common router for many library functions.

Below is a template for a Python MRE that you can paste into the issue template:

import switchyard
from switchyard.libsy import algorithms

def main():
    # Replace with the actual failing call

    try:
        result = algorithms.some_algorithm(param=42)
        print("Result:", result)
    except Exception as e:
        print("Caught exception:", e)
        raise

if __name__ == "__main__":
    main()

If the bug originates from the Rust implementation, provide a small Rust snippet that triggers the problem using the switchyard-rust crate. Compile and test your example independently to confirm it reproduces the error before submitting.

Document Your Environment

Accurate environment details are critical for reproduction. Run pip show switchyard to capture the installed version, or check switchyard/__init__.py directly for the version string. Include your operating system, Python version, and any relevant environment variables (with sensitive values redacted). For bugs involving routing algorithms, note whether you are using the pure Python implementation or the Rust backend.

Label and Submit the Issue

If you have repository permissions, add the bug label along with component-specific labels such as python, rust, or routing. These labels appear in the issue tracker and help maintainers triage efficiently. After verifying that no secrets or proprietary data appear in your logs or code snippets, click “Submit new issue.”

Follow Up and Contribute Fixes

Monitor the issue thread for clarification requests from maintainers. Timely responses keep the investigation moving forward. If you develop a fix, open a pull request that references the issue number in the description using the format Fixes #123 to automatically link the resolution.

Summary

• Search first to avoid duplicate reports in the NVIDIA-NeMo/Switchyard tracker.
• Use the template at .github/ISSUE_TEMPLATE/bug_report.md to structure your report.
• Provide an MRE under 30 lines that isolates the failure, targeting switchyard/libsy/algorithms.py for Python bugs.
• Include environment data from pip show switchyard or switchyard/__init__.py, plus full tracebacks.
• Label appropriately with bug and component tags if permissions allow.
• Follow up on questions and reference the issue in any related pull requests.

Frequently Asked Questions

Where can I find the official bug report template in Switchyard?

The official template is located at .github/ISSUE_TEMPLATE/bug_report.md in the repository root. When you click “New issue” in the GitHub interface, selecting the Bug report option automatically populates the description field with this template.

What constitutes a minimal reproducible example for Switchyard bugs?

A minimal reproducible example is a self-contained script, typically under 30 lines, that triggers the bug without external dependencies or proprietary data. For Python issues, import from switchyard.libsy.algorithms and demonstrate the exact call that raises an exception. For Rust issues, provide a small snippet using the switchyard-rust crate.

How do I safely check and report my Switchyard version?

Run pip show switchyard in your terminal to display the installed version, or inspect switchyard/__init__.py where the version is defined. When reporting, include the version string but ensure you remove any sensitive environment variables or API keys from your terminal output before pasting it into the issue.

Can I submit security vulnerabilities through public GitHub Issues?

The analysis provided does not specify a security reporting policy. For security-related bugs, check CONTRIBUTING.md or the repository's security documentation for private disclosure channels. Public issues should never contain exploit details or vulnerability proofs that could compromise users.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}