QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-04-07 10:31:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: bifurcate documentation into user and admin sections (#38196)

Browse Source 
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Evan Rusackas
2026-02-26 16:29:08 -05:00
committed by GitHub
parent 8a053bbe07
commit 6589ee48f9
171 changed files with 10899 additions and 2866 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
docs/developer_docs/contributing/code-review.md Normal file
View File

@@ -0,0 +1,339 @@
---
title: Code Review Process
sidebar_position: 4
---
<!--
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.
-->
# Code Review Process
Understand how code reviews work in Apache Superset and how to participate effectively.
## Overview
Code review is a critical part of maintaining code quality and sharing knowledge across the team. Every change to Superset goes through peer review before merging.
## For Authors
### Preparing for Review
#### Before Requesting Review
- [ ] Self-review your changes
- [ ] Ensure CI checks pass
- [ ] Add comprehensive tests
- [ ] Update documentation
- [ ] Fill out PR template completely
- [ ] Add screenshots for UI changes
#### Self-Review Checklist
```bash
# View your changes
git diff upstream/master
# Check for common issues:
# - Commented out code
# - Debug statements (console.log, print)
# - TODO comments that should be addressed
# - Hardcoded values that should be configurable
# - Missing error handling
# - Performance implications
```
### Requesting Review
#### Auto-Assignment
GitHub will automatically request reviews based on CODEOWNERS file.
#### Manual Assignment
For specific expertise, request additional reviewers:
- Frontend changes: Tag frontend experts
- Backend changes: Tag backend experts
- Security changes: Tag security team
- Database changes: Tag database experts
#### Review Request Message
```markdown
@reviewer This PR implements [feature]. Could you please review:
1. The approach taken in [file]
2. Performance implications of [change]
3. Security considerations for [feature]
Thanks!
```
### Responding to Feedback
#### Best Practices
- **Be receptive**: Reviews improve code quality
- **Ask questions**: Clarify if feedback is unclear
- **Explain decisions**: Share context for your choices
- **Update promptly**: Address feedback in timely manner
#### Comment Responses
```markdown
# Acknowledging
"Good catch! Fixed in [commit hash]"
# Explaining
"I chose this approach because [reason]. Would you prefer [alternative]?"
# Questioning
"Could you elaborate on [concern]? I'm not sure I understand the issue."
# Disagreeing respectfully
"I see your point, but I think [current approach] because [reason]. What do you think?"
```
## For Reviewers
### Review Responsibilities
#### What to Review
1. **Correctness**: Does the code do what it claims?
2. **Design**: Is the approach appropriate?
3. **Clarity**: Is the code readable and maintainable?
4. **Testing**: Are tests comprehensive?
5. **Performance**: Any performance concerns?
6. **Security**: Any security issues?
7. **Documentation**: Is it well documented?
### Review Checklist
#### Functionality
- [ ] Feature works as described
- [ ] Edge cases are handled
- [ ] Error handling is appropriate
- [ ] Backwards compatibility maintained
#### Code Quality
- [ ] Follows project conventions
- [ ] No code duplication
- [ ] Clear variable/function names
- [ ] Appropriate abstraction levels
- [ ] SOLID principles followed
#### Testing
- [ ] Unit tests for business logic
- [ ] Integration tests for APIs
- [ ] E2E tests for critical paths
- [ ] Tests are maintainable
- [ ] Good test coverage
#### Security
- [ ] Input validation
- [ ] SQL injection prevention
- [ ] XSS prevention
- [ ] CSRF protection
- [ ] Authentication/authorization checks
- [ ] No sensitive data in logs
#### Performance
- [ ] Database queries optimized
- [ ] No N+1 queries
- [ ] Appropriate caching
- [ ] Frontend bundle size impact
- [ ] Memory usage considerations
### Providing Feedback
#### Effective Comments
```python
# ✅ Good: Specific and actionable
"This query could cause N+1 problems. Consider using
`select_related('user')` to fetch users in a single query."
# ❌ Bad: Vague
"This doesn't look right."
```
```typescript
// ✅ Good: Suggests improvement
"Consider using useMemo here to prevent unnecessary
re-renders when dependencies haven't changed."
// ❌ Bad: Just criticism
"This is inefficient."
```
#### Comment Types
**Use GitHub's comment types:**
- **Comment**: General feedback or questions
- **Approve**: Changes look good
- **Request Changes**: Must be addressed before merge
**Prefix conventions:**
- `nit:` Minor issue (non-blocking)
- `suggestion:` Recommended improvement
- `question:` Seeking clarification
- `blocker:` Must be fixed
- `praise:` Highlighting good work
#### Examples
```markdown
nit: Consider renaming `getData` to `fetchUserData` for clarity
suggestion: This could be simplified using Array.reduce()
question: Is this intentionally not handling the error case?
blocker: This SQL is vulnerable to injection. Please use parameterized queries.
praise: Excellent test coverage! 👍
```
## Review Process
### Timeline
#### Expected Response Times
- **Initial review**: Within 2-3 business days
- **Follow-up review**: Within 1-2 business days
- **Critical fixes**: ASAP (tag in Slack)
#### Escalation
If no response after 3 days:
1. Ping reviewer in PR comments
2. Ask in #development Slack channel
3. Tag @apache/superset-committers
### Approval Requirements
#### Minimum Requirements
- **1 approval** from a committer for minor changes
- **2 approvals** for significant features
- **3 approvals** for breaking changes
#### Special Cases
- **Security changes**: Require security team review
- **API changes**: Require API team review
- **Database migrations**: Require database expert review
- **UI/UX changes**: Require design review
### Merge Process
#### Who Can Merge
- Committers with write access
- After all requirements met
- CI checks must pass
#### Merge Methods
- **Squash and merge**: Default for feature PRs
- **Rebase and merge**: For clean history
- **Create merge commit**: Rarely used
#### Merge Checklist
- [ ] All CI checks green
- [ ] Required approvals obtained
- [ ] No unresolved conversations
- [ ] PR title follows conventions
- [ ] Milestone set (if applicable)
## Review Etiquette
### Do's
- ✅ Be kind and constructive
- ✅ Acknowledge time and effort
- ✅ Provide specific examples
- ✅ Suggest solutions
- ✅ Praise good work
- ✅ Consider cultural differences
- ✅ Focus on the code, not the person
### Don'ts
- ❌ Use harsh or dismissive language
- ❌ Bikeshed on minor preferences
- ❌ Review when tired or frustrated
- ❌ Make personal attacks
- ❌ Ignore the PR description
- ❌ Demand perfection
## Becoming a Reviewer
### Path to Reviewer
1. **Contribute regularly**: Submit quality PRs
2. **Participate in discussions**: Share knowledge
3. **Review others' code**: Start with comments
4. **Build expertise**: Focus on specific areas
5. **Get nominated**: By existing committers
### Reviewer Expectations
- Review PRs in your area of expertise
- Respond within reasonable time
- Mentor new contributors
- Maintain high standards
- Stay current with best practices
## Advanced Topics
### Reviewing Large PRs
#### Strategy
1. **Request splitting**: Ask to break into smaller PRs
2. **Review in phases**:
- Architecture/approach first
- Implementation details second
- Tests and docs last
3. **Use draft reviews**: Save comments and submit together
### Cross-Team Reviews
#### When Needed
- Changes affecting multiple teams
- Shared components/libraries
- API contract changes
- Database schema changes
### Performance Reviews
#### Tools
```python
# Backend performance
import cProfile
import pstats
# Profile the code
cProfile.run('function_to_profile()', 'stats.prof')
stats = pstats.Stats('stats.prof')
stats.sort_stats('cumulative').print_stats(10)
```
```typescript
// Frontend performance
// Use React DevTools Profiler
// Chrome DevTools Performance tab
// Lighthouse audits
```
## Resources
### Internal
- [Coding Guidelines](../guidelines/design-guidelines)
- [Testing Guide](../testing/overview)
- [Extension Architecture](../extensions/architecture)
### External
- [Google's Code Review Guide](https://google.github.io/eng-practices/review/)
- [Best Practices for Code Review](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/)
- [The Art of Readable Code](https://www.oreilly.com/library/view/the-art-of/9781449318482/)
Next: [Reporting issues effectively](./issue-reporting)

1143
docs/developer_docs/contributing/development-setup.md Normal file
View File

File diff suppressed because it is too large Load Diff

415
docs/developer_docs/contributing/guidelines.md Normal file
View File

@@ -0,0 +1,415 @@
---
title: Contribution Guidelines
sidebar_position: 4
---
<!--
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.
-->
# Contribution Guidelines
## Pull Request Guidelines
A philosophy we would like to strongly encourage is
> Before creating a PR, create an issue.
The purpose is to separate problem from possible solutions.
**Bug fixes:** If you're only fixing a small bug, it's fine to submit a pull request right away but we highly recommend filing an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. Please keep in mind that the project maintainers reserve the rights to accept or reject incoming PRs, so it is better to separate the issue and the code to fix it from each other. In some cases, project maintainers may request you to create a separate issue from PR before proceeding.
**Refactor:** For small refactors, it can be a standalone PR itself detailing what you are refactoring and why. If there are concerns, project maintainers may request you to create a `#SIP` for the PR before proceeding.
**Feature/Large changes:** If you intend to change the public API, or make any non-trivial changes to the implementation, we require you to file a new issue as `#SIP` (Superset Improvement Proposal). This lets us reach an agreement on your proposal before you put significant effort into it. You are welcome to submit a PR along with the SIP (sometimes necessary for demonstration), but we will not review/merge the code until the SIP is approved.
In general, small PRs are always easier to review than large PRs. The best practice is to break your work into smaller independent PRs and refer to the same issue. This will greatly reduce turnaround time.
If you wish to share your work which is not ready to merge yet, create a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/). This will enable maintainers and the CI runner to prioritize mature PR's.
Finally, never submit a PR that will put master branch in broken state. If the PR is part of multiple PRs to complete a large feature and cannot work on its own, you can create a feature branch and merge all related PRs into the feature branch before creating a PR from feature branch to master.
### Protocol
#### Authoring
- Fill in all sections of the PR template.
- Title the PR with one of the following semantic prefixes (inspired by [Karma](http://karma-runner.github.io/0.10/dev/git-commit-msg.html])):
- `feat` (new feature)
- `fix` (bug fix)
- `docs` (changes to the documentation)
- `style` (formatting, missing semi colons, etc; no application logic change)
- `refactor` (refactoring code)
- `test` (adding missing tests, refactoring tests; no application logic change)
- `chore` (updating tasks etc; no application logic change)
- `perf` (performance-related change)
- `build` (build tooling, Docker configuration change)
- `ci` (test runner, GitHub Actions workflow changes)
- `other` (changes that don't correspond to the above -- should be rare!)
- Examples:
- `feat: export charts as ZIP files`
- `perf(api): improve API info performance`
- `fix(chart-api): cached-indicator always shows value is cached`
- Add prefix `[WIP]` to title if not ready for review (WIP = work-in-progress). We recommend creating a PR with `[WIP]` first and remove it once you have passed CI test and read through your code changes at least once.
- If you believe your PR contributes a potentially breaking change, put a `!` after the semantic prefix but before the colon in the PR title, like so: `feat!: Added foo functionality to bar`
- **Screenshots/GIFs:** Changes to user interface require before/after screenshots, or GIF for interactions
- Recommended capture tools ([Kap](https://getkap.co/), [LICEcap](https://www.cockos.com/licecap/), [Skitch](https://download.cnet.com/Skitch/3000-13455_4-189876.html))
- If no screenshot is provided, the committers will mark the PR with `need:screenshot` label and will not review until screenshot is provided.
- **Dependencies:** Be careful about adding new dependency and avoid unnecessary dependencies.
- For Python, include it in `pyproject.toml` denoting any specific restrictions and
in `requirements.txt` pinned to a specific version which ensures that the application
build is deterministic.
- For TypeScript/JavaScript, include new libraries in `package.json`
- **Tests:** The pull request should include tests, either as doctests, unit tests, or both. Make sure to resolve all errors and test failures. See [Testing](./howtos#testing) for how to run tests.
- **Documentation:** If the pull request adds functionality, the docs should be updated as part of the same PR.
- **CI:** Reviewers will not review the code until all CI tests are passed. Sometimes there can be flaky tests. You can close and open PR to re-run CI test. Please report if the issue persists. After the CI fix has been deployed to `master`, please rebase your PR.
- **Code coverage:** Please ensure that code coverage does not decrease.
- Remove `[WIP]` when ready for review. Please note that it may be merged soon after approved so please make sure the PR is ready to merge and do not expect more time for post-approval edits.
- If the PR was not ready for review and inactive for > 30 days, we will close it due to inactivity. The author is welcome to re-open and update.
#### Reviewing
- Use constructive tone when writing reviews.
- If there are changes required, state clearly what needs to be done before the PR can be approved.
- If you are asked to update your pull request with some changes there's no need to create a new one. Push your changes to the same branch.
- The committers reserve the right to reject any PR and in some cases may request the author to file an issue.
#### Test Environments
- Members of the Apache GitHub org can launch an ephemeral test environment directly on a pull request by creating a comment containing (only) the command `/testenv up`.
- Note that org membership must be public in order for this validation to function properly.
- Feature flags may be set for a test environment by specifying the flag name (prefixed with `FEATURE_`) and value after the command.
- Format: `/testenv up FEATURE_<feature flag name>=true|false`
- Example: `/testenv up FEATURE_DASHBOARD_NATIVE_FILTERS=true`
- Multiple feature flags may be set in single command, separated by whitespace
- A comment will be created by the workflow script with the address and login information for the ephemeral environment.
- Test environments may be created once the Docker build CI workflow for the PR has completed successfully.
- Test environments do not currently update automatically when new commits are added to a pull request.
- Test environments do not currently support async workers, though this is planned.
- Running test environments will be shutdown upon closing the pull request.
You can also access per-PR ephemeral environment directly using the following URL pattern:
`https://pr-{PR_NUMBER}.superset.apache.org`
#### Merging
- At least one approval is required for merging a PR.
- PR is usually left open for at least 24 hours before merging.
- After the PR is merged, [close the corresponding issue(s)](https://help.github.com/articles/closing-issues-using-keywords/).
#### Post-merge Responsibility
- Project maintainers may contact the PR author if new issues are introduced by the PR.
- Project maintainers may revert your changes if a critical issue is found, such as breaking master branch CI.
## Managing Issues and PRs
To handle issues and PRs that are coming in, committers read issues/PRs and flag them with labels to categorize and help contributors spot where to take actions, as contributors usually have different expertises.
Triaging goals
- **For issues:** Categorize, screen issues, flag required actions from authors.
- **For PRs:** Categorize, flag required actions from authors. If PR is ready for review, flag required actions from reviewers.
First, add **Category labels (a.k.a. hash labels)**. Every issue/PR must have one hash label (except spam entry). Labels that begin with `#` defines issue/PR type:
| Label | for Issue | for PR |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `#bug` | Bug report | Bug fix |
| `#code-quality` | Describe problem with code, architecture or productivity | Refactor, tests, tooling |
| `#feature` | New feature request | New feature implementation |
| `#refine` | Propose improvement such as adjusting padding or refining UI style, excluding new features, bug fixes, and refactoring. | Implementation of improvement such as adjusting padding or refining UI style, excluding new features, bug fixes, and refactoring. |
| `#doc` | Documentation | Documentation |
| `#question` | Troubleshooting: Installation, Running locally, Ask how to do something. Can be changed to `#bug` later. | N/A |
| `#SIP` | Superset Improvement Proposal | N/A |
| `#ASF` | Tasks related to Apache Software Foundation policy | Tasks related to Apache Software Foundation policy |
Then add other types of labels as appropriate.
- **Descriptive labels (a.k.a. dot labels):** These labels that begin with `.` describe the details of the issue/PR, such as `.ui`, `.js`, `.install`, `.backend`, etc. Each issue/PR can have zero or more dot labels.
- **Need labels:** These labels have pattern `need:xxx`, which describe the work required to progress, such as `need:rebase`, `need:update`, `need:screenshot`.
- **Risk labels:** These labels have pattern `risk:xxx`, which describe the potential risk on adopting the work, such as `risk:db-migration`. The intention was to better understand the impact and create awareness for PRs that need more rigorous testing.
- **Status labels:** These labels describe the status (`abandoned`, `wontfix`, `cant-reproduce`, etc.) Issue/PRs that are rejected or closed without completion should have one or more status labels.
- **Version labels:** These have the pattern `vx.x` such as `v0.28`. Version labels on issues describe the version the bug was reported on. Version labels on PR describe the first release that will include the PR.
Committers may also update title to reflect the issue/PR content if the author-provided title is not descriptive enough.
If the PR passes CI tests and does not have any `need:` labels, it is ready for review, add label `review` and/or `design-review`.
If an issue/PR has been inactive for at least 30 days, it will be closed. If it does not have any status label, add `inactive`.
When creating a PR, if you're aiming to have it included in a specific release, please tag it with the version label. For example, to have a PR considered for inclusion in Superset 1.1 use the label `v1.1`.
## Revert Guidelines
Reverting changes that are causing issues in the master branch is a normal and expected part of the development process. In an open source community, the ramifications of a change cannot always be fully understood. With that in mind, here are some considerations to keep in mind when considering a revert:
- **Availability of the PR author:** If the original PR author or the engineer who merged the code is highly available and can provide a fix in a reasonable time frame, this would counter-indicate reverting.
- **Severity of the issue:** How severe is the problem on master? Is it keeping the project from moving forward? Is there user impact? What percentage of users will experience a problem?
- **Size of the change being reverted:** Reverting a single small PR is a much lower-risk proposition than reverting a massive, multi-PR change.
- **Age of the change being reverted:** Reverting a recently-merged PR will be more acceptable than reverting an older PR. A bug discovered in an older PR is unlikely to be causing widespread serious issues.
- **Risk inherent in reverting:** Will the reversion break critical functionality? Is the medicine more dangerous than the disease?
- **Difficulty of crafting a fix:** In the case of issues with a clear solution, it may be preferable to implement and merge a fix rather than a revert.
Should you decide that reverting is desirable, it is the responsibility of the Contributor performing the revert to:
- **Contact the interested parties:** The PR's author and the engineer who merged the work should both be contacted and informed of the revert.
- **Provide concise reproduction steps:** Ensure that the issue can be clearly understood and duplicated by the original author of the PR.
- **Put the revert through code review:** The revert must be approved by another committer.
**Revert liberally to keep `master` stable**:
- Build failures
- Test failures
- Critical bugs in production
- Security vulnerabilities
**How to revert**:
1. Use GitHub's revert button when possible
2. Create a PR with clear explanation
3. Tag the original author
4. Work with them on a fix
## Design Guidelines
### Capitalization Guidelines
#### Sentence case
Use sentence-case capitalization for everything in the UI (except these **).
Sentence case is predominantly lowercase. Capitalize only the initial character of the first word, and other words that require capitalization, like:
- **Proper nouns.** Objects in the product _are not_ considered proper nouns e.g. dashboards, charts, saved queries etc. Proprietary feature names eg. SQL Lab, Preset Manager _are_ considered proper nouns
- **Acronyms** (e.g. CSS, HTML)
- When referring to **UI labels that are themselves capitalized** from sentence case (e.g. page titles - Dashboards page, Charts page, Saved queries page, etc.)
- User input that is reflected in the UI. E.g. a user-named a dashboard tab
**Sentence case vs. Title case:**
Title case: "A Dog Takes a Walk in Paris"
Sentence case: "A dog takes a walk in Paris"
**Why sentence case?**
- It's generally accepted as the quickest to read
- It's the easiest form to distinguish between common and proper nouns
**Good examples:**
- "Select a database"
- "Create new chart"
- "View all dashboards"
**Bad examples:**
- "Select a Database"
- "Create New Chart"
- "View All Dashboards"
#### How to refer to UI elements
When writing about a UI element, use the same capitalization as used in the UI.
For example, if an input field is labeled "Name" then you refer to this as the "Name input field". Similarly, if a button has the label "Save" in it, then it is correct to refer to the "Save button".
Where a product page is titled "Settings", you refer to this in writing as follows:
"Edit your personal information on the Settings page".
Often a product page will have the same title as the objects it contains. In this case, refer to the page as it appears in the UI, and the objects as common nouns:
- Upload a dashboard on the Dashboards page
- Go to Dashboards
- View dashboard
- View all dashboards
- Upload CSS templates on the CSS templates page
- Queries that you save will appear on the Saved queries page
- Create custom queries in SQL Lab then create dashboards
When writing about UI elements:
- Use **bold** for clickable elements: "Click **Save**"
- Use quotes for text fields: 'Enter "My Dashboard" in the name field'
- Be specific about element types: button, link, dropdown, etc.
#### **Exceptions to sentence case
Only use title case for:
- Product names (Apache Superset)
- Proper nouns
- Acronyms (SQL, API, CSV)
- Input labels, buttons and UI tabs are all caps
- User input values (e.g. column names, SQL Lab tab names) should be in their original case
## Programming Language Conventions
### Python
We use:
- **[Ruff](https://docs.astral.sh/ruff/)** for linting and formatting
- **[Mypy](http://mypy-lang.org/)** for type checking
Python code should:
- Follow PEP 8
- Use type hints for all new code
- Use descriptive variable names
- Include docstrings for modules, classes, and functions
- Handle exceptions appropriately
- Avoid global variables
Parameters in the `config.py` (which are accessible via the Flask app.config dictionary) are
assumed to always be defined and thus should be accessed directly via,
```python
blueprints = app.config["BLUEPRINTS"]
```
rather than,
```python
blueprints = app.config.get("BLUEPRINTS")
```
or similar as the later will cause typing issues. The former is of type `List[Callable]`
whereas the later is of type `Optional[List[Callable]]`.
#### Typing / Type Hints
All new Python code should include type hints:
To ensure clarity, consistency, all readability, _all_ new functions should use
[type hints](https://docs.python.org/3/library/typing.html) and include a
docstring.
Note per [PEP-484](https://www.python.org/dev/peps/pep-0484/#exceptions) no
syntax for listing explicitly raised exceptions is proposed and thus the
recommendation is to put this information in a docstring, i.e.,
```python
import math
from typing import List, Optional, Dict, Any, Union
def sqrt(x: Union[float, int]) -> Union[float, int]:
"""
Return the square root of x.
:param x: A number
:returns: The square root of the given number
:raises ValueError: If the number is negative
"""
return math.sqrt(x)
def process_data(
data: List[Dict[str, Any]],
filter_empty: bool = True
) -> Optional[Dict[str, Any]]:
"""
Process a list of data dictionaries.
Args:
data: List of dictionaries containing data
filter_empty: Whether to filter empty entries
Returns:
Processed data dictionary or None if no valid data
"""
if not data:
return None
# Process data...
return processed_data
```
Use `mypy` to check types:
```bash
mypy superset
```
### TypeScript
We use:
- **ESLint** for linting
- **Prettier** for formatting
- **TypeScript** strict mode
TypeScript is fully supported and is the recommended language for writing all new frontend
components. When modifying existing functions/components, migrating to TypeScript is
appreciated, but not required. Examples of migrating functions/components to TypeScript can be
found in [#9162](https://github.com/apache/superset/pull/9162) and [#9180](https://github.com/apache/superset/pull/9180).
TypeScript code should:
- Avoid `any` types - use proper TypeScript types
- Use functional components with hooks for React
- Include JSDoc comments for complex functions
- Use consistent naming conventions
- Handle errors appropriately
Example:
```typescript
interface User {
id: number;
name: string;
email?: string;
}
export function processUser(user: User): string {
// Avoid using 'any'
const { name, email } = user;
return email ? `${name} <${email}>` : name;
}
```
## Additional Guidelines
### Commit Messages
- Use clear, descriptive commit messages
- Start with a verb in imperative mood
- Reference issue numbers when applicable
Good: "Fix dashboard filter bug when dataset is deleted"
Bad: "Fixed stuff"
### Code Review Etiquette
- Be respectful and constructive
- Focus on the code, not the person
- Provide specific suggestions for improvement
- Acknowledge good work
- Be open to different approaches
### Documentation
- Update docs for any user-facing changes
- Include code examples where helpful
- Keep language clear and concise
- Test documentation changes locally
### Security
- Never commit secrets or credentials
- Validate all user input
- Use parameterized queries for SQL
- Follow OWASP guidelines
- Report security issues privately to private@superset.apache.org
## Questions?
If you have questions about these guidelines, ask in:
- [Slack #development](https://apache-superset.slack.com)
- [GitHub Discussions](https://github.com/apache/superset/discussions)

593
docs/developer_docs/contributing/howtos.md Normal file
View File

@@ -0,0 +1,593 @@
---
title: Development How-tos
sidebar_position: 7
---
<!--
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.
-->
# Development How-tos
This guide contains specific instructions for common development tasks in Superset.
## Contributing to Documentation
The documentation site is built using [Docusaurus](https://docusaurus.io/). All documentation lives in the `docs` folder, written in Markdown format.
### Local Development
To set up your local environment for documentation development:
```bash
cd docs
npm install
npm run start
```
The site will be available at http://localhost:3000
### Build
To create a production build:
```bash
npm run build
npm run serve # Test the build locally
```
### Deployment
Documentation is automatically deployed when changes are merged to master.
## Creating Visualization Plugins
Visualization plugins allow you to add custom chart types to Superset. They are built as npm packages that integrate with the Superset frontend.
### Prerequisites
- Node.js 18+
- npm or yarn
- A local Superset development environment
### Creating a simple Hello World viz plugin
1. **Install the Superset Yeoman generator**:
```bash
npm install -g @superset-ui/generator-superset
```
2. **Create a new plugin**:
```bash
mkdir superset-plugin-chart-hello-world
cd superset-plugin-chart-hello-world
yo @superset-ui/superset
```
3. **Follow the prompts**:
- Package name: `superset-plugin-chart-hello-world`
- Chart type: Choose your preferred type
- Include storybook: Yes (recommended for development)
4. **Develop your plugin**:
The generator creates a complete plugin structure with TypeScript, React components, and build configuration.
5. **Test your plugin locally**:
```bash
npm run dev
```
6. **Link to your local Superset**:
```bash
npm link
# In your Superset frontend directory:
npm link superset-plugin-chart-hello-world
```
7. **Import and register in Superset**:
Edit `superset-frontend/src/visualizations/presets/MainPreset.ts` to include your plugin.
## Testing
### Python Testing
Run Python tests using pytest:
```bash
# Run all tests
pytest
# Run specific test file
pytest tests/unit_tests/test_specific.py
# Run with coverage
pytest --cov=superset
# Run only unit tests
pytest tests/unit_tests
# Run only integration tests
pytest tests/integration_tests
```
#### Testing with local Presto connections
To test against Presto:
```bash
# Start Presto locally using Docker
docker run -p 8080:8080 \
--name presto \
-d prestodb/presto
# Configure in superset_config.py
SQLALCHEMY_DATABASE_URI = 'presto://localhost:8080/hive/default'
```
### Frontend Testing
Run frontend tests using Jest:
```bash
cd superset-frontend
# Run all tests
npm run test
# Run with coverage
npm run test -- --coverage
# Run in watch mode
npm run test -- --watch
# Run specific test file
npm run test -- MyComponent.test.tsx
```
### E2E Integration Testing
We support both Playwright (recommended) and Cypress for end-to-end testing.
#### Playwright (Recommended - NEW)
Playwright is our new E2E testing framework, gradually replacing Cypress.
```bash
# Navigate to frontend directory
cd superset-frontend
# Run all Playwright tests
npm run playwright:test
# or: npx playwright test
# Run with interactive UI for debugging
npm run playwright:ui
# or: npx playwright test --ui
# Run in headed mode (see browser)
npm run playwright:headed
# or: npx playwright test --headed
# Run specific test file
npx playwright test tests/auth/login.spec.ts
# Run with debug mode (step through tests)
npm run playwright:debug tests/auth/login.spec.ts
# or: npx playwright test --debug tests/auth/login.spec.ts
# Generate test report
npm run playwright:report
```
#### Cypress (DEPRECATED - will be removed)
Cypress is being phased out in favor of Playwright but is still available:
```bash
# Set base URL for Cypress
export CYPRESS_BASE_URL='http://localhost:8088'
export CYPRESS_DATABASE=test
export CYPRESS_USERNAME=admin
export CYPRESS_PASSWORD=admin
# Navigate to Cypress directory
cd superset-frontend/cypress-base
# Run interactively
npm run cypress-debug
# Run headless (like CI)
npm run cypress-run-chrome
# Run specific file
npm run cypress-run-chrome -- --spec "cypress/e2e/dashboard/dashboard.test.ts"
```
### Debugging Server App
For debugging the Flask backend:
#### Using PyCharm/IntelliJ
1. Create a new Python configuration
2. Set script path to `superset/app.py`
3. Set environment variables:
- `FLASK_ENV=development`
- `SUPERSET_CONFIG_PATH=/path/to/superset_config.py`
4. Set breakpoints and run in debug mode
#### Using VS Code
1. Add to `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Flask",
"type": "python",
"request": "launch",
"module": "flask",
"env": {
"FLASK_APP": "superset/app.py",
"FLASK_ENV": "development"
},
"args": ["run", "--no-debugger", "--no-reload"],
"jinja": true
}
]
}
```
2. Set breakpoints and press F5 to debug
### Debugging Server App in Kubernetes Environment
To debug Flask running in a POD inside a kubernetes cluster, you'll need to make sure the pod runs as root and is granted the `SYS_PTRACE` capability. These settings should not be used in production environments.
```yaml
securityContext:
capabilities:
add: ["SYS_PTRACE"]
```
See [set capabilities for a container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-capabilities-for-a-container) for more details.
Once the pod is running as root and has the `SYS_PTRACE` capability it will be able to debug the Flask app.
You can follow the same instructions as in `docker compose`. Enter the pod and install the required library and packages: gdb, netstat and debugpy.
Often in a Kubernetes environment nodes are not addressable from outside the cluster. VSCode will thus be unable to remotely connect to port 5678 on a Kubernetes node. In order to do this you need to create a tunnel that port forwards 5678 to your local machine.
```bash
kubectl port-forward pod/superset-<some random id> 5678:5678
```
You can now launch your VSCode debugger with the same config as above. VSCode will connect to 127.0.0.1:5678 which is forwarded by kubectl to your remote kubernetes POD.
### Storybook
See the dedicated [Storybook documentation](../testing/storybook) for information on running Storybook locally and adding new stories.
## Contributing Translations
Superset uses Flask-Babel for internationalization.
### Enabling language selection
Edit `superset_config.py`:
```python
LANGUAGES = {
'en': {'flag': 'us', 'name': 'English'},
'fr': {'flag': 'fr', 'name': 'French'},
'zh': {'flag': 'cn', 'name': 'Chinese'},
}
```
### Creating a new language dictionary
```bash
# Initialize a new language
pybabel init -i superset/translations/messages.pot -d superset/translations -l de
```
### Extracting new strings for translation
```bash
# Extract Python strings
pybabel extract -F babel.cfg -o superset/translations/messages.pot -k lazy_gettext superset
# Extract JavaScript strings
npm run build-translation
```
### Updating language files
```bash
# Update all language files with new strings
pybabel update -i superset/translations/messages.pot -d superset/translations
```
### Applying translations
```bash
# Frontend
cd superset-frontend
npm run build-translation
# Backend
pybabel compile -d superset/translations
```
## Linting
### Python
We use Ruff for Python linting and formatting:
```bash
# Auto-format using ruff
ruff format .
# Lint check with ruff
ruff check .
# Lint fix with ruff
ruff check --fix .
```
Pre-commit hooks run automatically on `git commit` if installed.
### TypeScript / JavaScript
We use a hybrid linting approach combining OXC (Oxidation Compiler) for standard rules and a custom AST-based checker for Superset-specific patterns.
#### Quick Commands
```bash
cd superset-frontend
# Run both OXC and custom rules
npm run lint:full
# Run OXC linter only (faster for most checks)
npm run lint
# Fix auto-fixable issues with OXC
npm run lint-fix
# Run custom rules checker only
npm run check:custom-rules
# Run tsc (typescript) checks
npm run type
# Format with Prettier
npm run prettier
```
#### Architecture
The linting system consists of two components:
1. **OXC Linter** (`oxlint`) - A Rust-based linter that's 50-100x faster than ESLint
- Handles all standard JavaScript/TypeScript rules
- Configured via `oxlint.json`
- Runs via `npm run lint` or `npm run lint-fix`
2. **Custom Rules Checker** - A Node.js AST-based checker for Superset-specific patterns
- Enforces no literal colors (use theme colors)
- Prevents FontAwesome usage (use @superset-ui/core Icons)
- Validates i18n template usage (no template variables)
- Runs via `npm run check:custom-rules`
#### Why This Approach?
- **50-100x faster linting** compared to ESLint for standard rules via OXC
- **Apache-compatible** - No custom binaries, ASF-friendly
- **Maintainable** - Custom rules in JavaScript, not Rust
- **Flexible** - Can evolve as OXC adds plugin support
#### Troubleshooting
**"Plugin 'basic-custom-plugin' not found" Error**
Ensure you're using the explicit config:
```bash
npx oxlint --config oxlint.json
```
**Custom Rules Not Running**
Verify the AST parsing dependencies are installed:
```bash
npm ls @babel/parser @babel/traverse glob
```
#### Adding New Custom Rules
1. Edit `scripts/check-custom-rules.js`
2. Add a new check function following the AST visitor pattern
3. Call the function in `processFile()`
4. Test with `npm run check:custom-rules`
## GitHub Ephemeral Environments
For every PR, an ephemeral environment is automatically deployed for testing.
Access pattern: `https://pr-{PR_NUMBER}.superset.apache.org`
Features:
- Automatically deployed on PR creation/update
- Includes sample data
- Destroyed when PR is closed
- Useful for UI/UX review
## Tips and Tricks
### Using Docker for Development
```bash
# Rebuild specific service
docker compose build superset
# View logs
docker compose logs -f superset
# Execute commands in container
docker compose exec superset bash
# Reset database
docker compose down -v
docker compose up
```
### Hot Reloading
**Frontend**: Webpack dev server provides hot module replacement automatically.
**Backend**: Use Flask debug mode:
```bash
FLASK_ENV=development superset run -p 8088 --with-threads --reload
```
### Performance Profiling
For Python profiling:
```python
# In superset_config.py
PROFILING = True
```
For React profiling:
- Use React DevTools Profiler
- Enable performance marks in Chrome DevTools
### Database Migrations
```bash
# Create a new migration
superset db migrate -m "Description of changes"
# Apply migrations
superset db upgrade
# Downgrade
superset db downgrade
```
### Useful Aliases
Add to your shell profile:
```bash
alias sdev='FLASK_ENV=development superset run -p 8088 --with-threads --reload'
alias stest='pytest tests/unit_tests'
alias slint='pre-commit run --all-files'
alias sfront='cd superset-frontend && npm run dev-server'
```
## Common Issues and Solutions
### Node/npm Issues
```bash
# Clear npm cache
npm cache clean --force
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```
### Python Environment Issues
```bash
# Recreate virtual environment
deactivate
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements/development.txt
pip install -e .
```
### Database Issues
```bash
# Reset local database
superset db downgrade -r base
superset db upgrade
superset init
```
### Port Already in Use
```bash
# Find process using port
lsof -i :8088
# Kill process
kill -9 [PID]
```
## Reporting Security Vulnerabilities
Please report security vulnerabilities to **private@superset.apache.org**.
In the event a community member discovers a security flaw in Superset, it is important to follow the [Apache Security Guidelines](https://www.apache.org/security/committers.html) and release a fix as quickly as possible before public disclosure. Reporting security vulnerabilities through the usual GitHub Issues channel is not ideal as it will publicize the flaw before a fix can be applied.
## SQL Lab Async Configuration
It's possible to configure a local database to operate in `async` mode, to work on `async` related features.
To do this, you'll need to:
- Add an additional database entry. We recommend you copy the connection string from the database labeled `main`, and then enable `SQL Lab` and the features you want to use. Don't forget to check the `Async` box
- Configure a results backend, here's a local `FileSystemCache` example, not recommended for production, but perfect for testing (stores cache in `/tmp`)
```python
from flask_caching.backends.filesystemcache import FileSystemCache
RESULTS_BACKEND = FileSystemCache('/tmp/sqllab')
```
- Start up a celery worker
```bash
celery --app=superset.tasks.celery_app:app worker -O fair
```
Note that:
- for changes that affect the worker logic, you'll have to restart the `celery worker` process for the changes to be reflected.
- The message queue used is a `sqlite` database using the `SQLAlchemy` experimental broker. Ok for testing, but not recommended in production
- In some cases, you may want to create a context that is more aligned to your production environment, and use the similar broker as well as results backend configuration
## Async Chart Queries
It's possible to configure database queries for charts to operate in `async` mode. This is especially useful for dashboards with many charts that may otherwise be affected by browser connection limits. To enable async queries for dashboards and Explore, the following dependencies are required:
- Redis 5.0+ (the feature utilizes [Redis Streams](https://redis.io/topics/streams-intro))
- Cache backends enabled via the `CACHE_CONFIG` and `DATA_CACHE_CONFIG` config settings
- Celery workers configured and running to process async tasks
## Need Help?
- Check the [FAQ](https://superset.apache.org/docs/frequently-asked-questions)
- Ask in [Slack](https://apache-superset.slack.com)
- Search [GitHub Issues](https://github.com/apache/superset/issues)
- Post in [GitHub Discussions](https://github.com/apache/superset/discussions)

418
docs/developer_docs/contributing/issue-reporting.md Normal file
View File

@@ -0,0 +1,418 @@
---
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)

166
docs/developer_docs/contributing/overview.md Normal file
View File

@@ -0,0 +1,166 @@
---
title: Overview
sidebar_position: 1
---
<!--
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.
-->
# Contributing
Superset is an [Apache Software foundation](https://www.apache.org/theapacheway/index.html) project.
The core contributors (or committers) to Superset communicate primarily in the following channels (which can be joined by anyone):
- [Mailing list](https://lists.apache.org/list.html?dev@superset.apache.org)
- [Apache Superset Slack community](http://bit.ly/join-superset-slack)
- [GitHub issues](https://github.com/apache/superset/issues)
- [GitHub pull requests](https://github.com/apache/superset/pulls)
- [GitHub discussions](https://github.com/apache/superset/discussions)
- [Superset Community Calendar](https://superset.apache.org/community)
More references:
- [Superset Wiki (code guidelines and additional resources)](https://github.com/apache/superset/wiki)
## Orientation
Here's a list of repositories that contain Superset-related packages:
- [apache/superset](https://github.com/apache/superset)
is the main repository containing the `apache_superset` Python package
distributed on
[pypi](https://pypi.org/project/apache_superset/). This repository
also includes Superset's main TypeScript/JavaScript bundles and react apps under
the [superset-frontend](https://github.com/apache/superset/tree/master/superset-frontend)
folder.
- [github.com/apache-superset](https://github.com/apache-superset) is the
GitHub organization under which we manage Superset-related
small tools, forks and Superset-related experimental ideas.
## Types of Contributions
### Report Bug
The best way to report a bug is to file an issue on GitHub. Please include:
- Your operating system name and version.
- Superset version.
- Detailed steps to reproduce the bug.
- Any details about your local setup that might be helpful in troubleshooting.
When posting Python stack traces, please quote them using
[Markdown blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks/).
_Please note that feature requests opened as GitHub Issues will be moved to Discussions._
### Submit Ideas or Feature Requests
The best way is to start an ["Ideas" Discussion thread](https://github.com/apache/superset/discussions/categories/ideas) on GitHub:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that your contributions are as welcome as anyone's :)
To propose large features or major changes to codebase, and help usher in those changes, please create a **Superset Improvement Proposal (SIP)**. See template from [SIP-0](https://github.com/apache/superset/issues/5602)
### Fix Bugs
Look through the GitHub issues. Issues tagged with `#bug` are
open to whoever wants to implement them.
### Implement Features
Look through the GitHub issues. Issues tagged with
`#feature` are open to whoever wants to implement them.
### Improve Documentation
Superset could always use better documentation,
whether as part of the official Superset docs,
in docstrings, `docs/*.rst` or even on the web as blog posts or
articles. See [Documentation](./howtos#contributing-to-documentation) for more details.
### Add Translations
If you are proficient in a non-English language, you can help translate
text strings from Superset's UI. You can jump into the existing
language dictionaries at
`superset/translations/<language_code>/LC_MESSAGES/messages.po`, or
even create a dictionary for a new language altogether.
See [Translating](./howtos#contributing-translations) for more details.
### Ask Questions
There is a dedicated [`apache-superset` tag](https://stackoverflow.com/questions/tagged/apache-superset) on [StackOverflow](https://stackoverflow.com/). Please use it when asking questions.
## Types of Contributors
Following the project governance model of the Apache Software Foundation (ASF), Apache Superset has a specific set of contributor roles:
### PMC Member
A Project Management Committee (PMC) member is a person who has been elected by the PMC to help manage the project. PMC members are responsible for the overall health of the project, including community development, release management, and project governance. PMC members are also responsible for the technical direction of the project.
For more information about Apache Project PMCs, please refer to https://www.apache.org/foundation/governance/pmcs.html
### Committer
A committer is a person who has been elected by the PMC to have write access (commit access) to the code repository. They can modify the code, documentation, and website and accept contributions from others.
The official list of committers and PMC members can be found [here](https://projects.apache.org/committee.html?superset).
### Contributor
A contributor is a person who has contributed to the project in any way, including but not limited to code, tests, documentation, issues, and discussions.
> You can also review the Superset project's guidelines for PMC member promotion here: https://github.com/apache/superset/wiki/Guidelines-for-promoting-Superset-Committers-to-the-Superset-PMC
### Security Team
The security team is a selected subset of PMC members, committers and non-committers who are responsible for handling security issues.
New members of the security team are selected by the PMC members in a vote. You can request to be added to the team by sending a message to private@superset.apache.org. However, the team should be small and focused on solving security issues, so the requests will be evaluated on a case-by-case basis and the team size will be kept relatively small, limited to only actively security-focused contributors.
This security team must follow the [ASF vulnerability handling process](https://apache.org/security/committers.html#asf-project-security-for-committers).
Each new security issue is tracked as a JIRA ticket on the [ASF's JIRA Superset security project](https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=588&projectKey=SUPERSETSEC)
Security team members must:
- Have an [ICLA](https://www.apache.org/licenses/contributor-agreements.html) signed with Apache Software Foundation.
- Not reveal information about pending and unfixed security issues to anyone (including their employers) unless specifically authorised by the security team members, e.g., if the security team agrees that diagnosing and solving an issue requires the involvement of external experts.
A release manager, the contributor overseeing the release of a specific version of Apache Superset, is by default a member of the security team. However, they are not expected to be active in assessing, discussing, and fixing security issues.
Security team members should also follow these general expectations:
- Actively participate in assessing, discussing, fixing, and releasing security issues in Superset.
- Avoid discussing security fixes in public forums. Pull request (PR) descriptions should not contain any information about security issues. The corresponding JIRA ticket should contain a link to the PR.
- Security team members who contribute to a fix may be listed as remediation developers in the CVE report, along with their job affiliation (if they choose to include it).
## Getting Started
Ready to contribute? Here's how to get started:
1. **[Set up your environment](./development-setup)** - Get Superset running locally
2. **[Find something to work on](#types-of-contributions)** - Pick an issue or feature
3. **[Submit your contribution](./submitting-pr)** - Create a pull request
4. **[Follow guidelines](./guidelines)** - Ensure code quality
Welcome to the Apache Superset community! 🚀

94
docs/developer_docs/contributing/pkg-resources-migration.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: pkg_resources Migration Guide
sidebar_position: 9
---
<!--
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.
-->
# pkg_resources Deprecation and Migration Guide
## Background
As of setuptools 81.0.0, the `pkg_resources` API is deprecated and will be removed. This affects several packages in the Python ecosystem.
## Current Status
### Superset Codebase
The Superset codebase has already migrated away from `pkg_resources` to the modern `importlib.metadata` API:
- `superset/db_engine_specs/__init__.py` - Uses `from importlib.metadata import entry_points`
- All entry point loading uses the modern API
### Production Dependencies
Some third-party dependencies may still use `pkg_resources`. Monitor your dependency tree for packages that haven't migrated yet.
## Migration Path
### Short-term Solution
Pin setuptools to version 80.x to prevent breaking changes:
```python
# requirements/base.in
setuptools<81
```
This prevents the removal of `pkg_resources` while dependent packages are updated.
### Long-term Solution
Update all dependencies to use `importlib.metadata` instead of `pkg_resources`:
#### Migration Example
**Old (deprecated):**
```python
import pkg_resources
version = pkg_resources.get_distribution("package_name").version
entry_points = pkg_resources.iter_entry_points("group_name")
```
**New (recommended):**
```python
from importlib.metadata import version, entry_points
pkg_version = version("package_name")
eps = entry_points(group="group_name")
```
## Action Items
### For Superset Maintainers
1. The Superset codebase already uses `importlib.metadata`
2. Monitor third-party dependencies for updates
3. Update setuptools pin once the ecosystem is ready
### For Extension Developers
1. **Update your packages** to use `importlib.metadata` instead of `pkg_resources`
2. **Test with setuptools >= 81.0.0** once all packages are migrated
## References
- [setuptools pkg_resources deprecation notice](https://setuptools.pypa.io/en/latest/pkg_resources.html)
- [importlib.metadata documentation](https://docs.python.org/3/library/importlib.metadata.html)
- [Migration guide](https://setuptools.pypa.io/en/latest/deprecated/pkg_resources.html)

469
docs/developer_docs/contributing/release-process.md Normal file
View File

@@ -0,0 +1,469 @@
---
title: Release Process
sidebar_position: 6
---
<!--
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.
-->
# Release Process
Understand Apache Superset's release process, versioning strategy, and how to participate.
## Release Cadence
### Schedule
- **Major releases (X.0.0)**: Annually (approximately)
- **Minor releases (X.Y.0)**: Quarterly
- **Patch releases (X.Y.Z)**: As needed for critical fixes
### Version Numbering
Superset follows [Semantic Versioning](https://semver.org/):
```
MAJOR.MINOR.PATCH
↓ ↓ ↓
│ │ └── Bug fixes, security patches
│ └────── New features, backwards compatible
└──────────── Breaking changes
```
### Examples
- `3.0.0`: Major release with breaking changes
- `3.1.0`: Minor release with new features
- `3.1.1`: Patch release with bug fixes
## Release Types
### Major Releases (X.0.0)
#### Includes
- Breaking API changes
- Deprecated feature removals
- Major architectural changes
- Database migration requirements
#### Process
- 2-3 month preparation period
- Multiple release candidates (RC)
- Extensive testing period
- Migration guides required
### Minor Releases (X.Y.0)
#### Includes
- New features
- Performance improvements
- Non-breaking API additions
- Minor UI/UX updates
#### Process
- 1 month preparation
- 1-2 release candidates
- Standard testing period
### Patch Releases (X.Y.Z)
#### Includes
- Bug fixes
- Security patches
- Documentation fixes
- Dependency updates (security)
#### Process
- Fast track for critical issues
- May skip RC for urgent security fixes
- Minimal testing requirements
## Release Process (For Release Managers)
### 1. Pre-Release Preparation
#### Feature Freeze
```bash
# Create release branch
git checkout -b release-X.Y
git push upstream release-X.Y
# Update version
# Edit setup.py and package.json
VERSION = "X.Y.0rc1"
```
#### Update Documentation
- CHANGELOG.md
- UPDATING.md (for breaking changes)
- Documentation version
#### Release Notes Template
```markdown
# Apache Superset X.Y.0
## 🎉 Highlights
- Major feature 1
- Major feature 2
## 🚀 New Features
- Feature 1 (#PR)
- Feature 2 (#PR)
## 🐛 Bug Fixes
- Fix 1 (#PR)
- Fix 2 (#PR)
## ⚠️ Breaking Changes
- Breaking change 1
- Migration required for X
## 📝 Documentation
- Doc update 1 (#PR)
## 🙏 Thank You
Thanks to all contributors!
```
### 2. Create Release Candidate
#### Build RC
```bash
# Tag release candidate
git tag -a vX.Y.Zrc1 -m "Apache Superset X.Y.Z RC1"
git push upstream vX.Y.Zrc1
# Build source distribution
python setup.py sdist
# Build wheel
python setup.py bdist_wheel
# Sign artifacts
gpg --armor --detach-sig dist/apache-superset-X.Y.Zrc1.tar.gz
```
#### Upload to staging
```bash
# Upload to Apache staging
svn co https://dist.apache.org/repos/dist/dev/superset
cd superset
mkdir X.Y.Zrc1
cp /path/to/dist/* X.Y.Zrc1/
svn add X.Y.Zrc1
svn commit -m "Add Apache Superset X.Y.Z RC1"
```
### 3. Voting Process
#### Call for Vote Email
Send to dev@superset.apache.org:
```
Subject: [VOTE] Release Apache Superset X.Y.Z RC1
Hi all,
I'd like to call a vote to release Apache Superset version X.Y.Z RC1.
The release candidate:
- Git tag: vX.Y.Zrc1
- Git hash: abc123def456
- Source: https://dist.apache.org/repos/dist/dev/superset/X.Y.Zrc1/
Resources:
- Release notes: [link]
- CHANGELOG: [link]
- PR list: [link]
The vote will be open for at least 72 hours.
[ ] +1 approve
[ ] +0 no opinion
[ ] -1 disapprove (and reason why)
Thanks,
[Your name]
```
#### Voting Rules
- **Duration**: Minimum 72 hours
- **Required**: 3 +1 votes from PMC members
- **Veto**: Any -1 vote must be addressed
#### Testing Checklist
```markdown
- [ ] Source builds successfully
- [ ] Docker image builds
- [ ] Basic functionality works
- [ ] No critical bugs
- [ ] License check passes
- [ ] Security scan clean
```
### 4. Release Approval
#### Tally Votes
```
Subject: [RESULT][VOTE] Release Apache Superset X.Y.Z RC1
The vote to release Apache Superset X.Y.Z RC1 has passed.
+1 votes (binding):
- PMC Member 1
- PMC Member 2
- PMC Member 3
+1 votes (non-binding):
- Contributor 1
- Contributor 2
0 votes:
- None
-1 votes:
- None
Thank you to everyone who tested and voted!
```
### 5. Perform Release
#### Promote RC to Release
```bash
# Tag final release
git tag -a vX.Y.Z -m "Apache Superset X.Y.Z"
git push upstream vX.Y.Z
# Move from dev to release
svn mv https://dist.apache.org/repos/dist/dev/superset/X.Y.Zrc1 \
https://dist.apache.org/repos/dist/release/superset/X.Y.Z
```
#### Publish to PyPI
```bash
# Upload to PyPI
python -m twine upload dist/*X.Y.Z*
```
#### Build Docker Images
```bash
# Build and push Docker images
docker build -t apache/superset:X.Y.Z .
docker push apache/superset:X.Y.Z
docker tag apache/superset:X.Y.Z apache/superset:latest
docker push apache/superset:latest
```
### 6. Post-Release Tasks
#### Update Documentation
```bash
# Update docs version
cd docs
# Update docusaurus.config.js with new version
npm run build
```
#### Announcement Email
Send to announce@apache.org, dev@superset.apache.org:
```
Subject: [ANNOUNCE] Apache Superset X.Y.Z Released
The Apache Superset team is pleased to announce the release of
Apache Superset X.Y.Z.
Apache Superset is a modern data exploration and visualization platform.
This release includes [number] commits from [number] contributors.
Highlights:
- Feature 1
- Feature 2
- Bug fixes and improvements
Download: https://superset.apache.org/docs/installation/
Release Notes: https://github.com/apache/superset/releases/tag/vX.Y.Z
PyPI: https://pypi.org/project/apache-superset/
Docker: docker pull apache/superset:X.Y.Z
Thanks to all contributors who made this release possible!
The Apache Superset Team
```
#### Update GitHub Release
```bash
# Create GitHub release
gh release create vX.Y.Z \
--title "Apache Superset X.Y.Z" \
--notes-file RELEASE_NOTES.md
```
## For Contributors
### During Feature Freeze
#### What's Allowed
- ✅ Bug fixes
- ✅ Documentation updates
- ✅ Test improvements
- ✅ Security fixes
#### What's Not Allowed
- ❌ New features
- ❌ Major refactoring
- ❌ Breaking changes
- ❌ Risky changes
### Testing RCs
#### How to Test
```bash
# Install RC from staging
pip install https://dist.apache.org/repos/dist/dev/superset/X.Y.Zrc1/apache-superset-X.Y.Zrc1.tar.gz
# Or use Docker
docker pull apache/superset:X.Y.Zrc1
```
#### What to Test
- Your use cases
- New features mentioned in release notes
- Upgrade from previous version
- Database migrations
- Critical workflows
#### Reporting Issues
```markdown
Found issue in RC1:
- Description: [what's wrong]
- Steps to reproduce: [how to trigger]
- Impact: [blocker/major/minor]
- Suggested fix: [if known]
```
### CHANGELOG Maintenance
#### Format
```markdown
## X.Y.Z (YYYY-MM-DD)
### Features
- feat: Description (#PR_NUMBER)
### Fixes
- fix: Description (#PR_NUMBER)
### Breaking Changes
- BREAKING: Description (#PR_NUMBER)
Migration: Steps to migrate
```
#### Generating CHANGELOG
```bash
# Use git log to generate initial list
git log --oneline vX.Y-1.Z..vX.Y.Z | grep -E "^[a-f0-9]+ (feat|fix|perf|refactor|docs)"
# Group by type and format
```
## Breaking Changes Process
### Documentation Required
#### UPDATING.md Entry
```markdown
# X.Y.Z
## Breaking Change: [Title]
### Description
What changed and why.
### Before
```python
# Old way
old_function(param1, param2)
```
### After
```python
# New way
new_function(param1, param2, param3)
```
### Migration Steps
1. Update your code to...
2. Run migration script...
3. Test that...
```
### Deprecation Process
1. **Version N**: Mark as deprecated
```python
@deprecated(version="3.0.0", remove_in="4.0.0")
def old_function():
warnings.warn("Use new_function instead", DeprecationWarning)
```
2. **Version N+1**: Keep deprecated with warnings
3. **Version N+2**: Remove completely
## Security Releases
### Expedited Process
- No RC required for critical security fixes
- Coordinate with security@apache.org
- Embargo period may apply
- CVE assignment through ASF security team
### Security Advisory Template
```markdown
CVE-YYYY-XXXXX: [Title]
Severity: [Critical/High/Medium/Low]
Affected Versions: < X.Y.Z
Fixed Version: X.Y.Z
Description:
[Vulnerability description]
Mitigation:
[How to fix or work around]
Credit:
[Reporter name/organization]
```
## Resources
### Internal
- [Apache Release Policy](https://www.apache.org/legal/release-policy.html)
- [Superset Release History](https://github.com/apache/superset/releases)
- [Version Strategy Discussion](https://github.com/apache/superset/discussions)
### Tools
- [Release Scripts](https://github.com/apache/superset/tree/master/scripts/release)
- [Superset Repository Scripts](https://github.com/apache/superset/tree/master/scripts)
Next: Return to [Contributing Overview](./overview)

133
docs/developer_docs/contributing/resources.md Normal file
View File

@@ -0,0 +1,133 @@
---
title: Resources
sidebar_position: 8
---
<!--
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.
-->
# Resources
## High Level Architecture
```mermaid
flowchart TD
%% Top Level
LB["<b>Load Balancer(s)</b><br/>(optional)"]
LB -.-> WebServers
%% Web Servers
subgraph WebServers ["<b>Web Server(s)</b>"]
WS1["<b>Frontend</b><br/>(React, AntD, ECharts, AGGrid)"]
WS2["<b>Backend</b><br/>(Python, Flask, SQLAlchemy, Pandas, ...)"]
end
%% Infra
subgraph InfraServices ["<b>Infra</b>"]
DB[("<b>Metadata Database</b><br/>(Postgres / MySQL)")]
subgraph Caching ["<b>Caching Subservices<br/></b>(Redis, memcache, S3, ...)"]
direction LR
DummySpace[" "]:::invisible
QueryCache["<b>Query Results Cache</b><br/>(Accelerated Dashboards)"]
CsvCache["<b>CSV Exports Cache</b>"]
ThumbnailCache["<b>Thumbnails Cache</b>"]
AlertImageCache["<b>Alert/Report Images Cache</b>"]
QueryCache -- " " --> CsvCache
linkStyle 1 stroke:transparent;
ThumbnailCache -- " " --> AlertImageCache
linkStyle 2 stroke:transparent;
end
Broker(("<b>Message Queue</b><br/>(Redis / RabbitMQ / SQS)"))
end
AsyncBackend["<b>Async Workers (Celery)</b><br>required for Alerts & Reports, thumbnails, CSV exports, long-running workloads, ..."]
%% External DBs
subgraph ExternalDatabases ["<b>Analytics Databases</b>"]
direction LR
BigQuery[(BigQuery)]
Snowflake[(Snowflake)]
Redshift[(Redshift)]
Postgres[(Postgres)]
Postgres[(... any ...)]
end
%% Connections
LB -.-> WebServers
WebServers --> DB
WebServers -.-> Caching
WebServers -.-> Broker
WebServers -.-> ExternalDatabases
Broker -.-> AsyncBackend
AsyncBackend -.-> ExternalDatabases
AsyncBackend -.-> Caching
%% Legend styling
classDef requiredNode stroke-width:2px,stroke:black;
class Required requiredNode;
class Optional optionalNode;
%% Hide real arrow
linkStyle 0 stroke:transparent;
%% Styling
classDef optionalNode stroke-dasharray: 5 5, opacity:0.9;
class LB optionalNode;
class Caching optionalNode;
class AsyncBackend optionalNode;
class Broker optionalNode;
class QueryCache optionalNode;
class CsvCache optionalNode;
class ThumbnailCache optionalNode;
class AlertImageCache optionalNode;
class Celery optionalNode;
classDef invisible fill:transparent,stroke:transparent;
```
## Entity-Relationship Diagram
For the full interactive Entity-Relationship Diagram, please visit the [developer documentation](/developer-docs/contributing/resources).
You can also [download the .svg](https://github.com/apache/superset/tree/master/docs/static/img/erd.svg) directly from GitHub.
## Additional Resources
### Official Documentation
- [Apache Superset Documentation](https://superset.apache.org/docs/intro)
- [API Documentation](https://superset.apache.org/docs/api)
- [Configuration Guide](https://superset.apache.org/admin-docs/configuration/configuring-superset)
### Community Resources
- [Apache Superset Blog](https://preset.io/blog/)
- [YouTube Channel](https://www.youtube.com/channel/UCMuwrvBsg_jjI2gLcm04R0g)
- [Twitter/X](https://twitter.com/ApacheSuperset)
### Development Tools
- [GitHub Repository](https://github.com/apache/superset)
- [PyPI Package](https://pypi.org/project/apache-superset/)
- [Docker Hub](https://hub.docker.com/r/apache/superset)
- [npm Packages](https://www.npmjs.com/search?q=%40superset-ui)

321
docs/developer_docs/contributing/submitting-pr.md Normal file
View File

@@ -0,0 +1,321 @@
---
title: Submitting Pull Requests
sidebar_position: 3
---
<!--
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.
-->
# Submitting Pull Requests
Learn how to create and submit high-quality pull requests to Apache Superset.
## Before You Start
### Prerequisites
- [ ] Development environment is set up
- [ ] You've forked and cloned the repository
- [ ] You've read the [contributing overview](./overview)
- [ ] You've found or created an issue to work on
### PR Readiness Checklist
- [ ] Code follows [coding guidelines](../guidelines/design-guidelines)
- [ ] Tests are passing locally
- [ ] Linting passes (`pre-commit run --all-files`)
- [ ] Documentation is updated if needed
## Creating Your Pull Request
### 1. Create a Feature Branch
```bash
# Update your fork
git fetch upstream
git checkout master
git merge upstream/master
git push origin master
# Create feature branch
git checkout -b feature/your-feature-name
```
### 2. Make Your Changes
```bash
# Make changes
edit files...
# Run tests
pytest tests/unit_tests/
cd superset-frontend && npm run test
# Run linting
pre-commit run --all-files
# Commit with conventional format
git add .
git commit -m "feat(dashboard): add new filter component"
```
### 3. PR Title Format
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
type(scope): description
```
**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, semicolons, etc.)
- `refactor`: Code refactoring
- `perf`: Performance improvement
- `test`: Adding tests
- `chore`: Maintenance tasks
- `ci`: CI/CD changes
- `build`: Build system changes
- `revert`: Reverting changes
**Scopes:**
- `dashboard`: Dashboard functionality
- `sqllab`: SQL Lab features
- `explore`: Chart explorer
- `chart`: Visualization components
- `api`: REST API endpoints
- `db`: Database connections
- `security`: Security features
- `config`: Configuration
**Examples:**
```
feat(sqllab): add query cost estimation
fix(dashboard): resolve filter cascading issue
docs(api): update REST endpoint documentation
refactor(explore): simplify chart controls logic
perf(dashboard): optimize chart loading
```
### 4. PR Description Template
Use the template from `.github/PULL_REQUEST_TEMPLATE.md`:
```markdown
### SUMMARY
Brief description of changes and motivation.
### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
[Required for UI changes]
### TESTING INSTRUCTIONS
1. Step-by-step instructions
2. How to verify the fix/feature
3. Any specific test scenarios
### ADDITIONAL INFORMATION
- [ ] Has associated issue: #12345
- [ ] Required feature flags:
- [ ] API changes:
- [ ] DB migration required:
### CHECKLIST
- [ ] CI checks pass
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] PR title follows conventions
```
### 5. Submit the PR
```bash
# Push to your fork
git push origin feature/your-feature-name
# Create PR via GitHub CLI
gh pr create --title "feat(sqllab): add query cost estimation" \
--body-file .github/PULL_REQUEST_TEMPLATE.md
# Or use the GitHub web interface
```
## PR Best Practices
### Keep PRs Focused
- One feature/fix per PR
- Break large changes into smaller PRs
- Separate refactoring from feature changes
### Write Good Commit Messages
```bash
# Good
git commit -m "fix(dashboard): prevent duplicate API calls when filters change"
# Bad
git commit -m "fix bug"
git commit -m "updates"
```
### Include Tests
```python
# Backend test example
def test_new_feature():
"""Test that new feature works correctly."""
result = new_feature_function()
assert result == expected_value
```
```typescript
// Frontend test example
test('renders new component', () => {
const { getByText } = render(<NewComponent />);
expect(getByText('Expected Text')).toBeInTheDocument();
});
```
### Add Screenshots for UI Changes
```markdown
### Before
![Before](link-to-before-screenshot)
### After
![After](link-to-after-screenshot)
```
### Update Documentation
- Update relevant docs in `/docs` directory
- Add docstrings to new functions/classes
- Update UPDATING.md for breaking changes
## CI Checks
### Required Checks
All PRs must pass:
- `Python Tests` - Backend unit/integration tests
- `Frontend Tests` - JavaScript/TypeScript tests
- `Linting` - Code style checks
- `Type Checking` - MyPy and TypeScript
- `License Check` - Apache license headers
- `Documentation Build` - Docs compile successfully
### Common CI Failures
#### Python Test Failures
```bash
# Run locally to debug
pytest tests/unit_tests/ -v
pytest tests/integration_tests/ -v
```
#### Frontend Test Failures
```bash
cd superset-frontend
npm run test -- --coverage
```
#### Linting Failures
```bash
# Auto-fix many issues
pre-commit run --all-files
# Manual fixes may be needed for:
# - MyPy type errors
# - Complex ESLint issues
# - License headers
```
## Responding to Reviews
### Address Feedback Promptly
```bash
# Make requested changes
edit files...
# Add commits (don't amend during review)
git add .
git commit -m "fix: address review feedback"
git push origin feature/your-feature-name
```
### Request Re-review
- Click "Re-request review" after addressing feedback
- Comment on resolved discussions
- Thank reviewers for their time
### Handling Conflicts
```bash
# Update your branch
git fetch upstream
git rebase upstream/master
# Resolve conflicts
edit conflicted files...
git add .
git rebase --continue
# Force push (only to your feature branch!)
git push --force-with-lease origin feature/your-feature-name
```
## After Merge
### Clean Up
```bash
# Delete local branch
git checkout master
git branch -d feature/your-feature-name
# Delete remote branch
git push origin --delete feature/your-feature-name
# Update your fork
git fetch upstream
git merge upstream/master
git push origin master
```
### Follow Up
- Monitor for any issues reported
- Help with documentation if needed
- Consider related improvements
## Tips for Success
### Do
- ✅ Keep PRs small and focused
- ✅ Write descriptive PR titles and descriptions
- ✅ Include tests for new functionality
- ✅ Respond to feedback constructively
- ✅ Update documentation
- ✅ Be patient with the review process
### Don't
- ❌ Submit PRs with failing tests
- ❌ Include unrelated changes
- ❌ Force push to master
- ❌ Ignore CI failures
- ❌ Skip the PR template
## Getting Help
- **Slack**: Ask in #development or #beginners
- **GitHub**: Tag @apache/superset-committers for attention
- **Mailing List**: dev@superset.apache.org
Next: [Understanding code review process](./code-review)