[SIP-0] Superset Improvement Proposals

[betodealmeida]

Superset Improvement Proposals

Purpose

The purpose of a Superset Improvement Proposal (SIP) is to introduce any major change into Apache Superset. This is required in order to balance the need to support new features, uses cases, while avoiding accidentally introducing half thought-out interfaces that cause needless problems when changed.

What is considered a major change that needs a SIP?

Any of the following should be considered a major change:

• Any major new feature, subsystem, or piece of functionality
• Any change that impacts the public interfaces of the project

What are the "public interfaces" of the project? All of the following are public interfaces that people build around:

• Visualization types
• Form data for saved dashboards and charts
• REST endpoints
• Data passed between backend and frontend
• Configuration
• Command line tools and arguments

What should be included in a SIP?

A SIP should contain the following sections:

• Motivation: describe the problem to be solved.
• Proposed Change: describe the new thing you want to do. This may be fairly extensive and have large subsections of its own. Or it may be a few sentences, depending on the scope of the change.
• New or Changed Public Interfaces: impact to any of the "compatibility commitments" described above. We want to call these out in particular so everyone thinks about them.
• New dependencies: describe any third-party libraries that the feature will require, from PyPI or NPM. In particular, make sure their license is compatible with the [Apache License v2.0] (https://www.apache.org/licenses/LICENSE-2.0).
• Migration Plan and Compatibility: if this feature requires additional support for seamless upgrades describe how that will work. In particular, it’s important to mention if:
  • The feature requires a database migration;
  • Dashboards and charts that are saved or bookmarked will still work after the change;
  • The feature will coexist with similar functionality for some period of time, allowing for a deprecation period.
• Rejected Alternatives: What are the other alternatives you considered and why are they worse? The goal of this section is to help people understand why this is the best solution now, and also to prevent churn in the future when old alternatives are reconsidered.

Who should initiate the SIP?

Anyone can initiate a SIP, but preferably someone with the intention of implementing it.

Process

1. Create an issue with the prefix “[SIP]” in the title. The issue will be tagged as “sip” by a committer, and the title will be updated with the current SIP number.
2. Notify the dev@ mailing list that the SIP has been created, use the subject line [DISCUSS] ..., the body of the email should look something like Please discuss & subscribe here: https://github.com/apache/incubator-superset/issues/5602
3. When writing the issue, fill in the sections as described above in “What should be included in a SIP?”. You can use the template included at the end of this document.
4. A committer will initiate the discussion and ensure that there’s enough time to analyze the proposal. Before accepting the SIP, a committer should call for a vote, requiring 3 votes and no vetoes—both from committers. Votes are timeboxed at 1 week, and conducted through email (with the subject line [VOTE] ...).
5. Create a pull request implementing the SIP, and referencing the issue.

Template

[SIP] Proposal for _

Motivation

Description of the problem to be solved.

Proposed Change

Describe how the feature will be implemented, or the problem will be solved. If possible, include mocks, screenshots, or screencasts (even if from different tools).

New or Changed Public Interfaces

Describe any new additions to the model, views or REST endpoints. Describe any changes to existing visualizations, dashboards and React components. Describe changes that affect the Superset CLI and how Superset is deployed.

New dependencies

Describe any NPM/PyPI packages that are required. Are they actively maintained? What are their licenses?

Migration Plan and Compatibility

Describe any database migrations that are necessary, or updates to stored URLs.

Rejected Alternatives

Describe alternative approaches that were considered and rejected.

[mistercrunch]

Updated to add step 2 Notify the dev@ mailing list that the SIP has been created to the process

[kristw]

@betodealmeida Would you like to call for votes in the mailing list for this proposal?

[nishantmonu51]

where should the discussion for the SIP take place ?
I believe, it could be either the dev list or the SIP issue itself.
doing on the dev list would make be easier for people not following the SIP issue itself to follow the discussion.

[kristw]

I believe, it could be either the dev list or the SIP issue itself.

I would vote for having the discussions on the SIP github issue.

• dev@ mailing list does not support images. There are many cases where screenshots/mocks/diagrams are necessary.
• Github issues allow editing, user tagging, images; and is generally much easier to read than a long email thread.

doing on the dev list would make be easier for people not following the SIP issue itself to follow the discussion.

With the proposed process, author will notify dev@ mailing list that a SIP has been created. Then people can subscribe/unsubscribe to notifications. This will let people subscribe only to the discussions they are interested.

[mistercrunch]

I agree with @kristw about having the discussion on Github. Images are a dealbreaker for a data visualization project. Also diagram and such.

[mistercrunch]

I amended the proposal, should we specify a process to amend post-vote? Btw having the diff of the history of the proposal is great:

[betodealmeida]

Closing this since it was voted.

[s1aw1k]

Good morning! Is there also a mobile app developer here?

[rusackas]

Please note that this SIP has passed, so SIPs will move forward (or not) according to this revised process.