superset2/docs/developer_docs_versioned_docs/version-6.1.0/contributing/issue-reporting.md

title, sidebar_position

title	sidebar_position
Issue Reporting	5

Issue Reporting

Learn how to effectively report bugs and request features for Apache Superset.

Before Opening an Issue

Pre-Issue Checklist

1. Search Existing Issues

   Search: https://github.com/apache/superset/issues
   - Use keywords from your error message
   - Check both open and closed issues
   - Look for similar problems
   

2. Check Documentation

   • User Documentation
   • FAQ
   • Configuration Guide

3. Verify Version

   # Check Superset version
   superset version
   
   # Try latest version
   pip install --upgrade apache-superset
   

4. Reproduce Consistently

   • Can you reproduce the issue?
   • Does it happen every time?
   • What specific actions trigger it?

Bug Reports

Bug Report Template

### Bug Description
A clear and concise description of the bug.

### How to Reproduce
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

### Expected Behavior
What you expected to happen.

### Actual Behavior
What actually happened. Include error messages.

### Screenshots/Videos
If applicable, add screenshots or recordings.

### Environment
- Superset version: [e.g., 3.0.0]
- Python version: [e.g., 3.9.7]
- Node version: [e.g., 18.17.0]
- Database: [e.g., PostgreSQL 14]
- Browser: [e.g., Chrome 120]
- OS: [e.g., Ubuntu 22.04]

### Additional Context
- Using Docker: Yes/No
- Configuration overrides:
- Feature flags enabled:
- Authentication method:

What Makes a Good Bug Report

✅ Good Example

### Bug Description
When filtering a dashboard with a date range filter, charts using
SQL Lab datasets don't update, while charts using regular datasets do.

### How to Reproduce
1. Create a dashboard with 2 charts:
   - Chart A: Uses a SQL Lab virtual dataset
   - Chart B: Uses a regular table dataset
2. Add a date range filter (last 30 days)
3. Apply the filter
4. Chart B updates, Chart A shows no change

### Expected Behavior
Both charts should filter to show last 30 days of data.

### Actual Behavior
Only Chart B updates. Chart A still shows all data.
No error messages in browser console or server logs.

### Screenshots
[Dashboard before filter]: attachment1.png
[Dashboard after filter]: attachment2.png
[Network tab showing requests]: attachment3.png

### Environment
- Superset version: 3.0.0
- Python version: 3.9.16
- Database: PostgreSQL 14.9
- Browser: Chrome 120.0.6099.71
- OS: macOS 14.2

❌ Poor Example

Dashboard filters don't work. Please fix.

Required Information

Error Messages

# Include full error traceback
Traceback (most recent call last):
  File "...", line X, in function
    error details
SupersetException: Detailed error message

Logs

# Backend logs
docker logs superset_app 2>&1 | tail -100

# Or from development
tail -f ~/.superset/superset.log

Browser Console

// Include JavaScript errors
// Chrome: F12 → Console tab
// Include network errors
// Chrome: F12 → Network tab

Configuration

# Relevant config from superset_config.py
FEATURE_FLAGS = {
    "ENABLE_TEMPLATE_PROCESSING": True,
    # ... other flags
}

Feature Requests

Feature Request Template

### Is your feature request related to a problem?
A clear description of the problem you're trying to solve.

### Describe the solution you'd like
A clear description of what you want to happen.

### Describe alternatives you've considered
Other solutions or features you've considered.

### Additional context
Any other context, mockups, or examples.

### Are you willing to contribute?
- [ ] Yes, I can implement this feature
- [ ] Yes, I can help test
- [ ] No, but I can provide feedback

Good Feature Requests Include

1. Clear Use Case

   As a [type of user], I want [feature] so that [benefit].
   
   Example:
   As a data analyst, I want to schedule dashboard screenshots
   so that I can automatically send reports to stakeholders.
   

2. Mockups/Designs

   • UI mockups
   • Workflow diagrams
   • API specifications

3. Impact Analysis

   • Who benefits?
   • How many users affected?
   • Performance implications?

Security Issues

🔴 IMPORTANT: Security Vulnerabilities

DO NOT create public issues for security vulnerabilities!

Instead:

1. Email: security@apache.org
2. Subject: [Superset] Security Vulnerability
3. Include:
   • Description of vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

Security Issue Template

Send to: security@apache.org

### Vulnerability Description
[Describe the security issue]

### Type
- [ ] SQL Injection
- [ ] XSS
- [ ] CSRF
- [ ] Authentication Bypass
- [ ] Information Disclosure
- [ ] Other: [specify]

### Affected Versions
[List affected versions]

### Steps to Reproduce
[Detailed steps - be specific]

### Impact
[What can an attacker do?]

### Suggested Fix
[If you have suggestions]

Issue Labels

Priority Labels

• P0: Critical - System unusable
• P1: High - Major feature broken
• P2: Medium - Important but workaround exists
• P3: Low - Nice to have

Type Labels

• bug: Something isn't working
• feature: New feature request
• enhancement: Improvement to existing feature
• documentation: Documentation improvements
• question: Question about usage

Component Labels

• dashboard: Dashboard functionality
• sqllab: SQL Lab
• explore: Chart builder
• visualization: Chart types
• api: REST API
• security: Security related

Status Labels

• needs-triage: Awaiting review
• confirmed: Bug confirmed
• in-progress: Being worked on
• blocked: Blocked by dependency
• stale: No activity for 30+ days

Issue Lifecycle

1. Creation

• User creates issue with template
• Auto-labeled as needs-triage

2. Triage

• Maintainer reviews within 7 days
• Labels applied (priority, type, component)
• Questions asked if needed

3. Confirmation

• Bug reproduced or feature discussed
• Label changed to confirmed
• Assigned to milestone if applicable

4. Development

• Contributor claims issue
• Label changed to in-progress
• PR linked to issue

5. Resolution

• PR merged
• Issue auto-closed
• Or manually closed with explanation

Following Up

If No Response

After 7 days without response:

@apache/superset-committers This issue hasn't been triaged yet.
Could someone please take a look?

Providing Updates

Update: I found that this only happens when [condition].
Here's additional debugging information: [details]

Issue Staleness

• Bot marks stale after 30 days of inactivity
• Closes after 7 more days without activity
• To keep open: Comment with updates

Tips for Success

Do's

• ✅ Search before creating
• ✅ Use templates
• ✅ Provide complete information
• ✅ Include screenshots/videos
• ✅ Be responsive to questions
• ✅ Test with latest version
• ✅ One issue per report

Don'ts

• ❌ "+1" or "me too" comments (use reactions)
• ❌ Multiple issues in one report
• ❌ Vague descriptions
• ❌ Screenshots of text (copy/paste instead)
• ❌ Private/sensitive data in reports
• ❌ Demanding immediate fixes

Useful Commands

Gathering System Info

# Full environment info
python -c "
import sys
import superset
import sqlalchemy
import pandas
import numpy

print(f'Python: {sys.version}')
print(f'Superset: {superset.__version__}')
print(f'SQLAlchemy: {sqlalchemy.__version__}')
print(f'Pandas: {pandas.__version__}')
print(f'NumPy: {numpy.__version__}')
"

# Database versions
superset shell
>>> from superset import db
>>> print(db.engine.dialect.server_version_info)

Creating Minimal Reproductions

# Create test script
# minimal_repro.py
from superset import create_app

app = create_app()
with app.app_context():
    # Your reproduction code here
    pass

Getting Help

Before Creating an Issue

1. Slack: Ask in #troubleshooting
2. GitHub Discussions: Search/ask questions
3. Stack Overflow: Tag apache-superset
4. Mailing List: user@superset.apache.org

Issue Not a Bug?

Consider:

• Feature Request: Use feature request template
• Question: Use GitHub Discussions
• Configuration Help: Ask in Slack
• Development Help: See Contributing Guide

Next: Understanding the release process