docs/developer_portal/contributing/issue-reporting.md - superset - Git at Google

 ---
 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.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
 ```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.9.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)

 Next: [Understanding the release process](./release-process)
	---
	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.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
	```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.9.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)

	Next: [Understanding the release process](./release-process)