| <!doctype html> |
| <html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-contributing/guidelines" data-has-hydrated="false"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="generator" content="Docusaurus v2.4.3"> |
| <title data-rh="true">Guidelines | Superset</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://superset.apache.org/docs/contributing/guidelines"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Guidelines | Superset"><meta data-rh="true" name="description" content="Pull Request Guidelines"><meta data-rh="true" property="og:description" content="Pull Request Guidelines"><link data-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://superset.apache.org/docs/contributing/guidelines"><link data-rh="true" rel="alternate" href="https://superset.apache.org/docs/contributing/guidelines" hreflang="en"><link data-rh="true" rel="alternate" href="https://superset.apache.org/docs/contributing/guidelines" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://WR5FASX5ED-dsn.algolia.net" crossorigin="anonymous"><link rel="search" type="application/opensearchdescription+xml" title="Superset" href="/opensearch.xml"> |
| |
| |
| |
| <script src="/script/matomo.js"></script><link rel="stylesheet" href="/assets/css/styles.72ccaccd.css"> |
| <link rel="preload" href="/assets/js/runtime~main.531f3acc.js" as="script"> |
| <link rel="preload" href="/assets/js/main.2efb21bb.js" as="script"> |
| </head> |
| <body class="navigation-with-keyboard"> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus"> |
| <div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/superset-logo-horiz.svg" alt="Superset Logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/superset-logo-horiz-dark.svg" alt="Superset Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div></a><div class="navbar__item dropdown dropdown--hoverable"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/docs/intro">Documentation</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/docs/intro">Getting Started</a></li><li><a class="dropdown__link" href="/docs/faq">FAQ</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/community">Community</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/community">Resources</a></li><li><a href="https://github.com/apache/superset" target="_blank" rel="noopener noreferrer" class="dropdown__link">GitHub<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="http://bit.ly/join-superset-slack" target="_blank" rel="noopener noreferrer" class="dropdown__link">Slack<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://lists.apache.org/list.html?dev@superset.apache.org" target="_blank" rel="noopener noreferrer" class="dropdown__link">Mailing List<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://stackoverflow.com/questions/tagged/apache-superset" target="_blank" rel="noopener noreferrer" class="dropdown__link">Stack Overflow<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="navbar__items navbar__items--right"><a class="navbar__item navbar__link default-button-theme get-started-button" href="/docs/intro">Get Started</a><a href="https://github.com/apache/superset" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link github-button"></a><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/intro">Introduction</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/quickstart">Quickstart</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/installation/kubernetes">Installation</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/configuration/configuring-superset">Configuration</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/using-superset/creating-your-first-dashboard">Using Superset</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/docs/contributing/">Contributing</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing/">Contributing to Superset</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/contributing/guidelines">Guidelines</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing/development">Setting up a Development Environment</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing/howtos">Development How-tos</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing/resources">Resources</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing/misc">Misc.</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/security/">Security</a></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/faq">FAQ</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/api">API</a></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_PEFL"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_kv0_"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><style data-emotion-css="hrzriw">.css-hrzriw{position:fixed;bottom:40px;right:10px;padding:1rem;padding-left:4rem;background-color:#444;border-radius:10px;z-index:9999;background-image:url('/img/github-dark.png');background-size:2rem;background-position:1rem center;background-repeat:no-repeat;-webkit-transition:background-color 0.3s;transition:background-color 0.3s;bpx-shadow:0 0 0 0 rgba(0,0,0,0);scale:.9;-webkit-transition:all 0.3s;transition:all 0.3s;-webkit-transform-origin:bottom right;-ms-transform-origin:bottom right;transform-origin:bottom right;}.css-hrzriw:hover{background-color:#333;box-shadow:5px 5px 10px 0 rgba(0,0,0,0.3);scale:1;}</style><a href="https://github.com/apache/superset/edit/master/docs/docs/contributing/guidelines.mdx" target="_blank" rel="noopener noreferrer" class="css-hrzriw">Edit this page on GitHub</a><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Contributing</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Guidelines</span><meta itemprop="position" content="2"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>Guidelines</h1></header><h2 class="anchor anchorWithStickyNavbar_LWe7" id="pull-request-guidelines">Pull Request Guidelines<a href="#pull-request-guidelines" class="hash-link" aria-label="Direct link to Pull Request Guidelines" title="Direct link to Pull Request Guidelines"></a></h2><p>A philosophy we would like to strongly encourage is</p><blockquote><p>Before creating a PR, create an issue.</p></blockquote><p>The purpose is to separate problem from possible solutions.</p><p><strong>Bug fixes:</strong> If you’re only fixing a small bug, it’s fine to submit a pull request right away but we highly recommend to file 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.</p><p><strong>Refactor:</strong> 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 <code>#SIP</code> for the PR before proceeding.</p><p><strong>Feature/Large changes:</strong> 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 <code>#SIP</code> (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.</p><p>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.</p><p>If you wish to share your work which is not ready to merge yet, create a <a href="https://github.blog/2019-02-14-introducing-draft-pull-requests/" target="_blank" rel="noopener noreferrer">Draft PR</a>. This will enable maintainers and the CI runner to prioritize mature PR's.</p><p>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.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="protocol">Protocol<a href="#protocol" class="hash-link" aria-label="Direct link to Protocol" title="Direct link to Protocol"></a></h3><h4 class="anchor anchorWithStickyNavbar_LWe7" id="authoring">Authoring<a href="#authoring" class="hash-link" aria-label="Direct link to Authoring" title="Direct link to Authoring"></a></h4><ul><li><p>Fill in all sections of the PR template.</p></li><li><p>Title the PR with one of the following semantic prefixes (inspired by <a href="http://karma-runner.github.io/0.10/dev/git-commit-msg.html%5D" target="_blank" rel="noopener noreferrer">Karma</a>):</p><ul><li><code>feat</code> (new feature)</li><li><code>fix</code> (bug fix)</li><li><code>docs</code> (changes to the documentation)</li><li><code>style</code> (formatting, missing semi colons, etc; no application logic change)</li><li><code>refactor</code> (refactoring code)</li><li><code>test</code> (adding missing tests, refactoring tests; no application logic change)</li><li><code>chore</code> (updating tasks etc; no application logic change)</li><li><code>perf</code> (performance-related change)</li><li><code>build</code> (build tooling, Docker configuration change)</li><li><code>ci</code> (test runner, GitHub Actions workflow changes)</li><li><code>other</code> (changes that don't correspond to the above -- should be rare!)</li><li>Examples:<ul><li><code>feat: export charts as ZIP files</code></li><li><code>perf(api): improve API info performance</code></li><li><code>fix(chart-api): cached-indicator always shows value is cached</code></li></ul></li></ul></li><li><p>Add prefix <code>[WIP]</code> to title if not ready for review (WIP = work-in-progress). We recommend creating a PR with <code>[WIP]</code> first and remove it once you have passed CI test and read through your code changes at least once.</p></li><li><p>If you believe your PR contributes a potentially breaking change, put a <code>!</code> after the semantic prefix but before the colon in the PR title, like so: <code>feat!: Added foo functionality to bar</code></p></li><li><p><strong>Screenshots/GIFs:</strong> Changes to user interface require before/after screenshots, or GIF for interactions</p><ul><li>Recommended capture tools (<a href="https://getkap.co/" target="_blank" rel="noopener noreferrer">Kap</a>, <a href="https://www.cockos.com/licecap/" target="_blank" rel="noopener noreferrer">LICEcap</a>, <a href="https://download.cnet.com/Skitch/3000-13455_4-189876.html" target="_blank" rel="noopener noreferrer">Skitch</a>)</li><li>If no screenshot is provided, the committers will mark the PR with <code>need:screenshot</code> label and will not review until screenshot is provided.</li></ul></li><li><p><strong>Dependencies:</strong> Be careful about adding new dependency and avoid unnecessary dependencies.</p><ul><li>For Python, include it in <code>pyproject.toml</code> denoting any specific restrictions and |
| in <code>requirements.txt</code> pinned to a specific version which ensures that the application |
| build is deterministic.</li><li>For TypeScript/JavaScript, include new libraries in <code>package.json</code></li></ul></li><li><p><strong>Tests:</strong> The pull request should include tests, either as doctests, unit tests, or both. Make sure to resolve all errors and test failures. See <a href="#testing">Testing</a> for how to run tests.</p></li><li><p><strong>Documentation:</strong> If the pull request adds functionality, the docs should be updated as part of the same PR.</p></li><li><p><strong>CI:</strong> 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 <code>master</code>, please rebase your PR.</p></li><li><p><strong>Code coverage:</strong> Please ensure that code coverage does not decrease.</p></li><li><p>Remove <code>[WIP]</code> 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.</p></li><li><p>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.</p></li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="reviewing">Reviewing<a href="#reviewing" class="hash-link" aria-label="Direct link to Reviewing" title="Direct link to Reviewing"></a></h4><ul><li>Use constructive tone when writing reviews.</li><li>If there are changes required, state clearly what needs to be done before the PR can be approved.</li><li>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.</li><li>The committers reserve the right to reject any PR and in some cases may request the author to file an issue.</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="test-environments">Test Environments<a href="#test-environments" class="hash-link" aria-label="Direct link to Test Environments" title="Direct link to Test Environments"></a></h4><ul><li>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 <code>/testenv up</code>.<ul><li>Note that org membership must be public in order for this validation to function properly.</li></ul></li><li>Feature flags may be set for a test environment by specifying the flag name (prefixed with <code>FEATURE_</code>) and value after the command.<ul><li>Format: <code>/testenv up FEATURE_<feature flag name>=true|false</code></li><li>Example: <code>/testenv up FEATURE_DASHBOARD_NATIVE_FILTERS=true</code></li><li>Multiple feature flags may be set in single command, separated by whitespace</li></ul></li><li>A comment will be created by the workflow script with the address and login information for the ephemeral environment.</li><li>Test environments may be created once the Docker build CI workflow for the PR has completed successfully.</li><li>Test environments do not currently update automatically when new commits are added to a pull request.</li><li>Test environments do not currently support async workers, though this is planned.</li><li>Running test environments will be shutdown upon closing the pull request.</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="merging">Merging<a href="#merging" class="hash-link" aria-label="Direct link to Merging" title="Direct link to Merging"></a></h4><ul><li>At least one approval is required for merging a PR.</li><li>PR is usually left open for at least 24 hours before merging.</li><li>After the PR is merged, <a href="https://help.github.com/articles/closing-issues-using-keywords/" target="_blank" rel="noopener noreferrer">close the corresponding issue(s)</a>.</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="post-merge-responsibility">Post-merge Responsibility<a href="#post-merge-responsibility" class="hash-link" aria-label="Direct link to Post-merge Responsibility" title="Direct link to Post-merge Responsibility"></a></h4><ul><li>Project maintainers may contact the PR author if new issues are introduced by the PR.</li><li>Project maintainers may revert your changes if a critical issue is found, such as breaking master branch CI.</li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="managing-issues-and-prs">Managing Issues and PRs<a href="#managing-issues-and-prs" class="hash-link" aria-label="Direct link to Managing Issues and PRs" title="Direct link to Managing Issues and PRs"></a></h2><p>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.</p><p>Triaging goals</p><ul><li><strong>For issues:</strong> Categorize, screen issues, flag required actions from authors.</li><li><strong>For PRs:</strong> Categorize, flag required actions from authors. If PR is ready for review, flag required actions from reviewers.</li></ul><p>First, add <strong>Category labels (a.k.a. hash labels)</strong>. Every issue/PR must have one hash label (except spam entry). Labels that begin with <code>#</code> defines issue/PR type:</p><table><thead><tr><th>Label</th><th>for Issue</th><th>for PR</th></tr></thead><tbody><tr><td><code>#bug</code></td><td>Bug report</td><td>Bug fix</td></tr><tr><td><code>#code-quality</code></td><td>Describe problem with code, architecture or productivity</td><td>Refactor, tests, tooling</td></tr><tr><td><code>#feature</code></td><td>New feature request</td><td>New feature implementation</td></tr><tr><td><code>#refine</code></td><td>Propose improvement such as adjusting padding or refining UI style, excluding new features, bug fixes, and refactoring.</td><td>Implementation of improvement such as adjusting padding or refining UI style, excluding new features, bug fixes, and refactoring.</td></tr><tr><td><code>#doc</code></td><td>Documentation</td><td>Documentation</td></tr><tr><td><code>#question</code></td><td>Troubleshooting: Installation, Running locally, Ask how to do something. Can be changed to <code>#bug</code> later.</td><td>N/A</td></tr><tr><td><code>#SIP</code></td><td>Superset Improvement Proposal</td><td>N/A</td></tr><tr><td><code>#ASF</code></td><td>Tasks related to Apache Software Foundation policy</td><td>Tasks related to Apache Software Foundation policy</td></tr></tbody></table><p>Then add other types of labels as appropriate.</p><ul><li><strong>Descriptive labels (a.k.a. dot labels):</strong> These labels that begin with <code>.</code> describe the details of the issue/PR, such as <code>.ui</code>, <code>.js</code>, <code>.install</code>, <code>.backend</code>, etc. Each issue/PR can have zero or more dot labels.</li><li><strong>Need labels:</strong> These labels have pattern <code>need:xxx</code>, which describe the work required to progress, such as <code>need:rebase</code>, <code>need:update</code>, <code>need:screenshot</code>.</li><li><strong>Risk labels:</strong> These labels have pattern <code>risk:xxx</code>, which describe the potential risk on adopting the work, such as <code>risk:db-migration</code>. The intention was to better understand the impact and create awareness for PRs that need more rigorous testing.</li><li><strong>Status labels:</strong> These labels describe the status (<code>abandoned</code>, <code>wontfix</code>, <code>cant-reproduce</code>, etc.) Issue/PRs that are rejected or closed without completion should have one or more status labels.</li><li><strong>Version labels:</strong> These have the pattern <code>vx.x</code> such as <code>v0.28</code>. 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.</li></ul><p>Committers may also update title to reflect the issue/PR content if the author-provided title is not descriptive enough.</p><p>If the PR passes CI tests and does not have any <code>need:</code> labels, it is ready for review, add label <code>review</code> and/or <code>design-review</code>.</p><p>If an issue/PR has been inactive for >=30 days, it will be closed. If it does not have any status label, add <code>inactive</code>.</p><p>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 <code>v1.1</code>.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="revert-guidelines">Revert Guidelines<a href="#revert-guidelines" class="hash-link" aria-label="Direct link to Revert Guidelines" title="Direct link to Revert Guidelines"></a></h2><p>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:</p><ul><li><strong>Availability of the PR author:</strong> 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.</li><li><strong>Severity of the issue:</strong> 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?</li><li><strong>Size of the change being reverted:</strong> Reverting a single small PR is a much lower-risk proposition than reverting a massive, multi-PR change.</li><li><strong>Age of the change being reverted:</strong> 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.</li><li><strong>Risk inherent in reverting:</strong> Will the reversion break critical functionality? Is the medicine more dangerous than the disease?</li><li><strong>Difficulty of crafting a fix:</strong> In the case of issues with a clear solution, it may be preferable to implement and merge a fix rather than a revert.</li></ul><p>Should you decide that reverting is desirable, it is the responsibility of the Contributor performing the revert to:</p><ul><li><strong>Contact the interested parties:</strong> The PR's author and the engineer who merged the work should both be contacted and informed of the revert.</li><li><strong>Provide concise reproduction steps:</strong> Ensure that the issue can be clearly understood and duplicated by the original author of the PR.</li><li><strong>Put the revert through code review:</strong> The revert must be approved by another committer.</li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="design-guidelines">Design Guidelines<a href="#design-guidelines" class="hash-link" aria-label="Direct link to Design Guidelines" title="Direct link to Design Guidelines"></a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="capitalization-guidelines">Capitalization guidelines<a href="#capitalization-guidelines" class="hash-link" aria-label="Direct link to Capitalization guidelines" title="Direct link to Capitalization guidelines"></a></h3><h4 class="anchor anchorWithStickyNavbar_LWe7" id="sentence-case">Sentence case<a href="#sentence-case" class="hash-link" aria-label="Direct link to Sentence case" title="Direct link to Sentence case"></a></h4><p>Use sentence-case capitalization for everything in the UI (except these <!-- -->*<!-- -->*<!-- -->).</p><p>Sentence case is predominantly lowercase. Capitalize only the initial character of the first word, and other words that require capitalization, like:</p><ul><li><strong>Proper nouns.</strong> Objects in the product <em>are not</em> considered proper nouns e.g. dashboards, charts, saved queries etc. Proprietary feature names eg. SQL Lab, Preset Manager <em>are</em> considered proper nouns</li><li><strong>Acronyms</strong> (e.g. CSS, HTML)</li><li>When referring to <strong>UI labels that are themselves capitalized</strong> from sentence case (e.g. page titles - Dashboards page, Charts page, Saved queries page, etc.)</li><li>User input that is reflected in the UI. E.g. a user-named a dashboard tab</li></ul><p><strong>Sentence case vs. Title case:</strong> |
| Title case: "A Dog Takes a Walk in Paris" |
| Sentence case: "A dog takes a walk in Paris"</p><p><strong>Why sentence case?</strong></p><ul><li>It’s generally accepted as the quickest to read</li><li>It’s the easiest form to distinguish between common and proper nouns</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="how-to-refer-to-ui-elements">How to refer to UI elements<a href="#how-to-refer-to-ui-elements" class="hash-link" aria-label="Direct link to How to refer to UI elements" title="Direct link to How to refer to UI elements"></a></h4><p>When writing about a UI element, use the same capitalization as used in the UI.</p><p>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”.</p><p>Where a product page is titled “Settings”, you refer to this in writing as follows: |
| “Edit your personal information on the Settings page”.</p><p>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:</p><ul><li>Upload a dashboard on the Dashboards page</li><li>Go to Dashboards</li><li>View dashboard</li><li>View all dashboards</li><li>Upload CSS templates on the CSS templates page</li><li>Queries that you save will appear on the Saved queries page</li><li>Create custom queries in SQL Lab then create dashboards</li></ul><h4 class="anchor anchorWithStickyNavbar_LWe7" id="exceptions-to-sentence-case">*<!-- -->*<!-- -->Exceptions to sentence case:<a href="#exceptions-to-sentence-case" class="hash-link" aria-label="Direct link to exceptions-to-sentence-case" title="Direct link to exceptions-to-sentence-case"></a></h4><ul><li>Input labels, buttons and UI tabs are all caps</li><li>User input values (e.g. column names, SQL Lab tab names) should be in their original case</li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="programming-language-conventions">Programming Language Conventions<a href="#programming-language-conventions" class="hash-link" aria-label="Direct link to Programming Language Conventions" title="Direct link to Programming Language Conventions"></a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="python">Python<a href="#python" class="hash-link" aria-label="Direct link to Python" title="Direct link to Python"></a></h3><p>Parameters in the <code>config.py</code> (which are accessible via the Flask app.config dictionary) are |
| assumed to always be defined and thus should be accessed directly via,</p><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">blueprints </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">config</span><span class="token punctuation" style="color:#393A34">[</span><span class="token string" style="color:#e3116c">"BLUEPRINTS"</span><span class="token punctuation" style="color:#393A34">]</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>rather than,</p><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain">blueprints </span><span class="token operator" style="color:#393A34">=</span><span class="token plain"> app</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">config</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">get</span><span class="token punctuation" style="color:#393A34">(</span><span class="token string" style="color:#e3116c">"BLUEPRINTS"</span><span class="token punctuation" style="color:#393A34">)</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>or similar as the later will cause typing issues. The former is of type <code>List[Callable]</code> |
| whereas the later is of type <code>Optional[List[Callable]]</code>.</p><h4 class="anchor anchorWithStickyNavbar_LWe7" id="typing--types-hints">Typing / Types Hints<a href="#typing--types-hints" class="hash-link" aria-label="Direct link to Typing / Types Hints" title="Direct link to Typing / Types Hints"></a></h4><p>To ensure clarity, consistency, all readability, <em>all</em> new functions should use |
| <a href="https://docs.python.org/3/library/typing.html" target="_blank" rel="noopener noreferrer">type hints</a> and include a |
| docstring.</p><p>Note per <a href="https://www.python.org/dev/peps/pep-0484/#exceptions" target="_blank" rel="noopener noreferrer">PEP-484</a> no |
| syntax for listing explicitly raised exceptions is proposed and thus the |
| recommendation is to put this information in a docstring, i.e.,</p><div class="language-python codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-python codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> math</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">from</span><span class="token plain"> typing </span><span class="token keyword" style="color:#00009f">import</span><span class="token plain"> Union</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token keyword" style="color:#00009f">def</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">sqrt</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">x</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"> Union</span><span class="token punctuation" style="color:#393A34">[</span><span class="token builtin">float</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">)</span><span class="token plain"> </span><span class="token operator" style="color:#393A34">-</span><span class="token operator" style="color:#393A34">></span><span class="token plain"> Union</span><span class="token punctuation" style="color:#393A34">[</span><span class="token builtin">float</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"> </span><span class="token builtin">int</span><span class="token punctuation" style="color:#393A34">]</span><span class="token punctuation" style="color:#393A34">:</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token triple-quoted-string string" style="color:#e3116c">"""</span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="color:#e3116c"> Return the square root of x.</span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="display:inline-block;color:#e3116c"></span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="color:#e3116c"> :param x: A number</span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="color:#e3116c"> :returns: The square root of the given number</span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="color:#e3116c"> :raises ValueError: If the number is negative</span><br></span><span class="token-line" style="color:#393A34"><span class="token triple-quoted-string string" style="color:#e3116c"> """</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token keyword" style="color:#00009f">return</span><span class="token plain"> math</span><span class="token punctuation" style="color:#393A34">.</span><span class="token plain">sqrt</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">x</span><span class="token punctuation" style="color:#393A34">)</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="typescript">TypeScript<a href="#typescript" class="hash-link" aria-label="Direct link to TypeScript" title="Direct link to TypeScript"></a></h3><p>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 <a href="https://github.com/apache/superset/pull/9162" target="_blank" rel="noopener noreferrer">#9162</a> and <a href="https://github.com/apache/superset/pull/9180" target="_blank" rel="noopener noreferrer">#9180</a>.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/apache/superset/edit/master/docs/docs/contributing/guidelines.mdx" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/contributing/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Contributing to Superset</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/contributing/development"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Setting up a Development Environment</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#pull-request-guidelines" class="table-of-contents__link toc-highlight">Pull Request Guidelines</a><ul><li><a href="#protocol" class="table-of-contents__link toc-highlight">Protocol</a></li></ul></li><li><a href="#managing-issues-and-prs" class="table-of-contents__link toc-highlight">Managing Issues and PRs</a></li><li><a href="#revert-guidelines" class="table-of-contents__link toc-highlight">Revert Guidelines</a></li><li><a href="#design-guidelines" class="table-of-contents__link toc-highlight">Design Guidelines</a><ul><li><a href="#capitalization-guidelines" class="table-of-contents__link toc-highlight">Capitalization guidelines</a></li></ul></li><li><a href="#programming-language-conventions" class="table-of-contents__link toc-highlight">Programming Language Conventions</a><ul><li><a href="#python" class="table-of-contents__link toc-highlight">Python</a></li><li><a href="#typescript" class="table-of-contents__link toc-highlight">TypeScript</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="footer__copyright"> |
| <div class="footer__applitools"> |
| We use <a href="https://applitools.com/" target="_blank" rel="nofollow"><img src="/img/applitools.png" title="Applitools"></a> |
| </div> |
| <p>Copyright © 2024, |
| The <a href="https://www.apache.org/" target="_blank" rel="noreferrer">Apache Software Foundation</a>, |
| Licensed under the Apache <a href="https://apache.org/licenses/LICENSE-2.0" target="_blank" rel="noreferrer">License</a>.</p> |
| <p><small>Apache Superset, Apache, Superset, the Superset logo, and the Apache feather logo are either registered trademarks or trademarks of The Apache Software Foundation. All other products or name brands are trademarks of their respective holders, including The Apache Software Foundation. |
| <a href="https://www.apache.org/" target="_blank">Apache Software Foundation</a> resources</small></p> |
| <img class="footer__divider" src="/img/community/line.png" alt="Divider"> |
| <p> |
| <small> |
| <a href="/docs/security/" target="_blank" rel="noreferrer">Security</a> | |
| <a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noreferrer">Donate</a> | |
| <a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noreferrer">Thanks</a> | |
| <a href="https://apache.org/events/current-event" target="_blank" rel="noreferrer">Events</a> | |
| <a href="https://apache.org/licenses/" target="_blank" rel="noreferrer">License</a> | |
| <a href="https://privacy.apache.org/policies/privacy-policy-public.html" target="_blank" rel="noreferrer">Privacy</a> |
| </small> |
| </p> |
| <!-- telemetry/analytics pixel: --> |
| <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=39ae6855-95fc-4566-86e5-360d542b0a68"> |
| </div></div></div></footer></div> |
| <script src="/assets/js/runtime~main.531f3acc.js"></script> |
| <script src="/assets/js/main.2efb21bb.js"></script> |
| </body> |
| </html> |
