Submitting Issues

GitHub Issues are our primary way to track bugs, feature requests, and discussions. This guide explains how to submit effective issues.

Before Submitting

  1. Search existing issues at https://github.com/SDNNetSim/FUSION/issues

  2. Check if it’s already fixed in the latest version

  3. Gather information about your environment and the problem

Creating an Issue

  1. Go to the Issues tab and click “New issue”

  2. GitHub will automatically show you the available templates:

    • Bug Report - For reporting problems

    • Feature Request - For suggesting new functionality

  3. Select a template and fill it out completely

Tip

The issue templates are YAML forms that guide you through providing all the necessary information. You can view the template files in the repository at .github/ISSUE_TEMPLATE/:

  • 01_bug_report.yml - Bug report template

  • 02_feature_request.yml - Feature request template

Bug Reports

When reporting a bug, the template will ask for:

Bug Summary

A clear, concise description of the problem.

Impact Level

How severely does this affect your work?

  • Critical: Simulation crashes or data corruption

  • High: Incorrect results or major functionality broken

  • Medium: Workflow disruption or performance issues

  • Low: Minor inconvenience or cosmetic issues

Affected Component

Which part of FUSION is affected (CLI, routing, spectrum, etc.)

Steps to Reproduce

Detailed steps to recreate the issue, including:

  • Configuration file used

  • Command executed

  • Step-by-step actions

Expected vs Actual Behavior

What should happen vs what actually happens.

Error Information

Full error messages and stack traces.

Environment Details

  • Operating system

  • Python version

  • FUSION version/branch

Example Bug Report

Bug Summary: Simulation crashes when using multi-core fiber with FirstFit

Impact Level: High

Steps to Reproduce:
1. Set num_cores = 7 in config
2. Run simulation with FirstFit spectrum assignment
3. Simulation crashes at ~500 arrivals

Expected: Simulation completes normally
Actual: Crashes with IndexError

Error:
IndexError: index 7 is out of bounds for axis 0 with size 7

Environment: Ubuntu 22.04, Python 3.11.5, main branch

Feature Requests

When requesting a feature, the template will ask for:

Feature Title

A concise name for the feature.

Priority Level

How important is this to you?

Problem Statement

What problem does this solve? What can’t users do currently?

Proposed Solution

Your suggested implementation approach.

Acceptance Criteria

What does “done” look like? Use checkboxes:

- [ ] Feature works with CLI
- [ ] Configuration validation updated
- [ ] Unit tests added
- [ ] Documentation updated

Example Feature Request

Feature Title: Add support for dynamic spectrum defragmentation

Priority: Medium

Problem Statement:
As a researcher studying spectrum efficiency, I want to simulate
defragmentation strategies so that I can compare their effectiveness.

Proposed Solution:
Add a DefragmentationPolicy interface with configurable strategies
(e.g., repack-left, minimize-moves) that can run periodically or
on-demand during simulation.

Acceptance Criteria:
- [ ] DefragmentationPolicy interface defined
- [ ] At least two strategies implemented
- [ ] Configuration options added
- [ ] Metrics for defragmentation events collected

Issue Labels

Our team uses labels to categorize and prioritize issues:

  • bug: Something isn’t working

  • enhancement: New feature or improvement

  • documentation: Documentation improvements

  • needs-triage: Needs team review

  • needs-discussion: Requires discussion before implementation

  • good first issue: Good for newcomers

Tips for Good Issues

  • Be specific: Include exact error messages, not paraphrases

  • Be complete: Fill out all template sections

  • Be minimal: If possible, create a minimal reproduction case

  • Be patient: Maintainers are volunteers; complex issues take time

  • Follow up: Respond to questions and provide additional info when asked