<h2 dir="auto">Motivation</h2>
<p dir="auto">Historically organizations partaking in the release process have managed their own fork of incubator-superset which is deployed in production via a Git submodule. Both companies have been actively developing Superset and deploy internally (features and bug fixes) at a higher cadence than the public PyPI releases. These forks came about because of the potential instability of the master branch (see <a href="https://github.com/apache/incubator-superset/issues/6132" data-hovercard-type="issue" data-hovercard-url="/apache/superset/issues/6132/hovercard">SIP-13</a>) and provided a mechanism to cherry-pick specific commits thus ensuring an increased stability.</p>
<p dir="auto">These organizations have discussed ways of trying to fold these forked branches back into the incubator-superset repo to better ensure consistency and to serve as a mechanism for formalizing the release process which is somewhat sporadic.</p>
<h2 dir="auto">Proposed Change</h2>
<p dir="auto">The proposed solution is based primarily on having release branches where certain organizations are the primary beta testers for stabilizing the branch.</p>
<h3 dir="auto">Master branch</h3>
<p dir="auto">There will be no changes to how the <code class="notranslate">master</code> branch currently works. We will do our best to keep the <code class="notranslate">master</code> branch healthy in part by the initiatives outlined in <a href="https://github.com/apache/incubator-superset/issues/6132" data-hovercard-type="issue" data-hovercard-url="/apache/superset/issues/6132/hovercard">SIP-13</a>. If you create a pull request, please do it against the <code class="notranslate">master</code> branch. We will maintain stable branches for releases separately but we don’t accept pull requests to them directly. Instead, we will cherry-pick non-breaking changes from <code class="notranslate">master</code> to the two latest releases.</p>
<h3 dir="auto">Release Cadence</h3>
<p dir="auto">We propose a regular release cadence of every <strong>two weeks</strong>. This period is a tradeoff between stability and flexibility ensuring that new features can be deployed within a reasonable time frame. Furthermore the longer the release cadence the greater the potential conflict when cherry-picking commits. A release will be deployed two weeks after it was cut.</p>
<p dir="auto">We propose that each release branch is fully managed by a single organization.</p>
<h3 dir="auto">Branch Naming</h3>
<p dir="auto">We propose that all Git branches follow the <code class="notranslate">&lt;prefix&gt;/&lt;suffix&gt;</code> naming convention:</p>
<ul dir="auto">
<li>Personal: <code class="notranslate">&lt;username&gt;/&lt;issue&gt;</code>, i.e., <code class="notranslate">jane-doe/issue-123</code></li>
<li>Feature: <code class="notranslate">feature/&lt;name&gt;</code>, i.e., <code class="notranslate">feature/dashboard-v2</code></li>
<li>Release: <code class="notranslate">release/&lt;version&gt;</code>, i.e., <code class="notranslate">release/1.1</code></li>
</ul>
<p dir="auto">Note if <code class="notranslate">/</code> is troublesome we suggest using a two hyphens (<code class="notranslate">--</code>) instead.</p>
<h3 dir="auto">Semantic Versioning</h3>
<p dir="auto">Superset follows semantic versioning (<code class="notranslate">&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;</code>) although the major version has remained fixed at zero. We should release patch versions for bug fixes, minor versions for new features, and the major version for breaking changes. When we make breaking changes, we should also introduce deprecation warnings in a minor version so that our users learn about the upcoming changes and migrate their code in advance.</p>
<p dir="auto">Git release branches represent the <code class="notranslate">&lt;major&gt;.&lt;minor&gt;</code> level whereas Git tags (associated with a specific commit) represent the fully defined <code class="notranslate">&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;</code> version. Note tags may contain an optional release candidate suffix (<code class="notranslate">-rc</code>).</p>
<h3 dir="auto">The Git Ecosystem</h3>
<p dir="auto">The following diagram describes the <code class="notranslate">apache/incubator-superset</code> Git ecosystem and how we plan to couple this with several organization's internal deployment (superset-internal which uses a Git submodule) which will help serve as a mechanism for stabilizing a release.</p>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/4567245/47102523-d96e2d00-d1f1-11e8-9291-a9addf007bac.png"><img src="https://user-images.githubusercontent.com/4567245/47102523-d96e2d00-d1f1-11e8-9291-a9addf007bac.png" alt="release" style="max-width: 100%;"></a></p>
<h4 dir="auto">Day 0</h4>
<p dir="auto">On day 0 the next release branch (<code class="notranslate">release/1.1</code>) will be cut from <code class="notranslate">master</code> which references the latest commit. The commit will be tagged with <code class="notranslate">v1.1.0-rc</code> (the v1.1.0 release candidate) and deployed to PyPI.</p>
<h4 dir="auto">Day 0 - 13</h4>
<p dir="auto">Only commits associated which resolve bugs present in the release candidate will be cherry-picked onto the release branch. Fixes to features added after the cut will not be cherry picked (†). Note there may be potential merge conflicts (which will have to be resolved) when cherry-picking a fix due to an upstream commit which is not in the release (‡). If this is too complex the cherry-pick should be skipped (---) as it will be included in the next release. New features can be committed on <code class="notranslate">master</code> <strong>if and only if</strong> they’re defined in their entirety within the two week cycle. Larger features should be developed on a feature specific branch (which is then merged into <code class="notranslate">master</code>) or using feature flags.</p>
<p dir="auto">The following diagram shows the use of a feature branch which spans multiple releases.</p>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/4567245/47102567-eee35700-d1f1-11e8-8b1b-3de48729ebc3.png"><img src="https://user-images.githubusercontent.com/4567245/47102567-eee35700-d1f1-11e8-8b1b-3de48729ebc3.png" alt="feature" style="max-width: 100%;"></a></p>
<h4 dir="auto">Day 7</h4>
<p dir="auto">Organizations partaking in the release process will update the Git submodule reference to point to the release (<code class="notranslate">release/1.1</code>). This seven day lag provides a soak period of ensuring that critical bugs are not deployed to our production environments. The update is made to the <code class="notranslate">.gitmodules</code> file,</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="[submodule &quot;incubator-superset&quot;]
    path = incubator-superset
    url = https://github.com/apache/incubator-superset
    branch = release/1.1"><pre class="notranslate"><code class="notranslate">[submodule "incubator-superset"]
    path = incubator-superset
    url = https://github.com/apache/incubator-superset
    branch = release/1.1
</code></pre></div>
<p dir="auto">which ensures it tracks the correct release branch. Like the two week release process the submodule branch will be updated every two weeks.</p>
<h4 dir="auto">Day 7 - 20</h4>
<p dir="auto">Periodically organizations partaking in the release process will ensure that the submodule in their internal deployment will reference the latest commit from the remote branch (which contains all the cherries) via,</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="git submodule update --remote --recursive --merge "><pre class="notranslate"><code class="notranslate">git submodule update --remote --recursive --merge 
</code></pre></div>
<p dir="auto">which will fetch the latest changes for each submodule, merge them in, and check out the latest revision of the submodule. This step allows us to further test and stabilize the branch in a production environment.</p>
<h4 dir="auto">Day 14</h4>
<p dir="auto">The first (non release candidate) version will be tagged (<code class="notranslate">v1.1.0</code>) and deployed to PyPI which references the latest commit on the branch (*). Simultaneously the next release branch (<code class="notranslate">release/1.2</code>) will be cut from <code class="notranslate">master</code> which will mimic <code class="notranslate">v1.1.0</code> except it will also include any feature commits which were merged in the past 14 days. Note a new release branch is cut if and only if feature commits were added, to prevent duplication.</p>
<p dir="auto">The following diagram shows an example where on day 14 a new release branch is not cut as there were no new features added since day 0. The next viable release cut date will then be day 28 to preserve the release cadence.</p>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/4567245/47102650-24884000-d1f2-11e8-8039-e01e55343e17.png"><img src="https://user-images.githubusercontent.com/4567245/47102650-24884000-d1f2-11e8-8039-e01e55343e17.png" alt="no-release" style="max-width: 100%;"></a></p>
<h4 dir="auto">Day 14 - 27</h4>
<p dir="auto">Additional bug fixes to commits in the release candidate will be cherry-picked onto the <em>n</em> most recent releases (where <em>n</em> = 2, i.e.,<code class="notranslate"> release/1.1</code> and <code class="notranslate">release/1.2</code>). Throughout this period the tag can be updated (incrementing the patch) as desired based on the severity of the fix.</p>
<h4 dir="auto">Day 28 -</h4>
<p dir="auto">Assuming there is a new release branch (<code class="notranslate">release/1.3</code>) we will no longer be picking cherries onto <code class="notranslate">release/1.1</code> since we only support two releases (<code class="notranslate">release/1.2</code> and <code class="notranslate">release/1.3</code>). In summary most release branches will have a four week active lifespan.</p>
<p dir="auto">Branches should exist for infinitum to ensure critical security fixes can be patched to the necessary branch.</p>
<h4 dir="auto">Database Migrations</h4>
<p dir="auto">Database migrations (which are handled via <a href="https://alembic.zzzcomputing.com/en/latest/" rel="nofollow">Alembic</a>) have an additional lineage component (used to determine upgrades and downgrades) which further complicates matters. We need to ensure the playback of versions is correct when upgrading to a newer release and that a downgrade is never necessary.</p>
<p dir="auto">The logic for cherry-picking migrations is similar to above whereas migrations can be cherry-picked onto a release branch <strong>if and only if</strong> all of its ancestors are present on the branch. Given that there no notion of resolving merge conflicts in Alembic, any migration (and thus future migrations) related to a feature will be skipped (<code class="notranslate">--</code>) and included in the next release.</p>
<h2 dir="auto">Action Items</h2>
<p dir="auto">Currently we plan on manually cherry-picking the commits from <code class="notranslate">master</code> to the desired release branch. This could be automated in the future based on PR tags and/or the assistance from a bot.</p>
<p dir="auto">We also should check with Apache whether there are any concerns/feasibility issues with releasing on a two week cadence.</p>
<p dir="auto"><a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/beto/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/beto">@beto</a> <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/mistercrunch/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/mistercrunch">@mistercrunch</a></p>
<p dir="auto">As a continuation feature to the native-filters left side panel there is a requirement on focusing users on charts  by a specific user-path in watch a short summary for the current active filters that applies the current scope in order to make the dashboard more readable oriented in the cases where dashboards are served as a client-facing application.</p>
<p dir="auto">For that we offer the Filter summary bar which it is another element that can be dragged into the dashboard layout (as charts, tabs , column ,row and etc') , which means it would be optional to use in each dashboard</p>
<h1 dir="auto">prototype</h1>
<p dir="auto"><a href="https://www.figma.com/proto/g3MebAB0lUc0aa5pLRcepn/Superset-Filter-Summary-Bar?page-id=0%3A1&amp;node-id=1%3A2&amp;scaling=min-zoom&amp;starting-point-node-id=1%3A2" rel="nofollow">Figma</a></p>
<h2 dir="auto">key features:</h2>
<ol dir="auto">
<li>the filter summary bar will always be displayed upon dragging it into the layout</li>
<li>upon scope change like tab change, filters will only display the active filters for that scope</li>
<li>the purpose of this is not to show accurate filters that are being applied as the filter indicator main purpose but just a summary of what filters are active on the scope</li>
</ol>
<p dir="auto">note: we might consider hiding(CSS) those chart filter indicators in order to focus the user on visualization themself but that is for the dashboard creator to decide on each dashboard separately</p>
<h2 dir="auto">backward compatibility:</h2>
<p dir="auto">if you don't drag the filter summary bar into the dashboard feature will not be used at all and existing functionality remains intact</p>
<h3 dir="auto">dashboard preview:</h3>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/47772523/137370293-cf9ae225-ac23-4c50-9825-d22bdb9c670b.png"><img src="https://user-images.githubusercontent.com/47772523/137370293-cf9ae225-ac23-4c50-9825-d22bdb9c670b.png" alt="image" style="max-width: 100%;"></a></p>
<h3 dir="auto">Summary Filter bar component</h3>
<p dir="auto"><a target="_blank" rel="noopener noreferrer nofollow" href="https://user-images.githubusercontent.com/47772523/137370427-f498cea8-94d9-4045-a90c-d23e1605a6e2.png"><img src="https://user-images.githubusercontent.com/47772523/137370427-f498cea8-94d9-4045-a90c-d23e1605a6e2.png" alt="image" style="max-width: 100%;"></a></p>