Spaces:
Paused
Paused
| title: Issue Reporting | |
| sidebar_position: 5 | |
| <!-- | |
| Licensed to the Apache Software Foundation (ASF) under one | |
| or more contributor license agreements. See the NOTICE file | |
| distributed with this work for additional information | |
| regarding copyright ownership. The ASF licenses this file | |
| to you under the Apache License, Version 2.0 (the | |
| "License"); you may not use this file except in compliance | |
| with the License. You may obtain a copy of the License at | |
| http://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, | |
| software distributed under the License is distributed on an | |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| KIND, either express or implied. See the License for the | |
| specific language governing permissions and limitations | |
| under the License. | |
| --> | |
| # 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](https://superset.apache.org/docs/intro) | |
| - [FAQ](https://superset.apache.org/docs/frequently-asked-questions) | |
| - [Configuration Guide](https://superset.apache.org/docs/configuration/configuring-superset) | |
| 3. **Verify Version** | |
| ```bash | |
| # 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 | |
| ```markdown | |
| ### 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.11.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 | |
| ```markdown | |
| ### 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.11.16 | |
| - Database: PostgreSQL 14.9 | |
| - Browser: Chrome 120.0.6099.71 | |
| - OS: macOS 14.2 | |
| ``` | |
| #### ❌ Poor Example | |
| ```markdown | |
| Dashboard filters don't work. Please fix. | |
| ``` | |
| ### Required Information | |
| #### Error Messages | |
| ```python | |
| # Include full error traceback | |
| Traceback (most recent call last): | |
| File "...", line X, in function | |
| error details | |
| SupersetException: Detailed error message | |
| ``` | |
| #### Logs | |
| ```bash | |
| # Backend logs | |
| docker logs superset_app 2>&1 | tail -100 | |
| # Or from development | |
| tail -f ~/.superset/superset.log | |
| ``` | |
| #### Browser Console | |
| ```javascript | |
| // Include JavaScript errors | |
| // Chrome: F12 → Console tab | |
| // Include network errors | |
| // Chrome: F12 → Network tab | |
| ``` | |
| #### Configuration | |
| ```python | |
| # Relevant config from superset_config.py | |
| FEATURE_FLAGS = { | |
| "ENABLE_TEMPLATE_PROCESSING": True, | |
| # ... other flags | |
| } | |
| ``` | |
| ## Feature Requests | |
| ### Feature Request Template | |
| ```markdown | |
| ### 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** | |
| ```markdown | |
| 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 | |
| ```markdown | |
| 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: | |
| ```markdown | |
| @apache/superset-committers This issue hasn't been triaged yet. | |
| Could someone please take a look? | |
| ``` | |
| ### Providing Updates | |
| ```markdown | |
| 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 | |
| ```bash | |
| # 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 | |
| ```python | |
| # 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](./overview.md) | |
| Next: [Understanding the release process](./release-process.md) | |