DingoDB Improvement Proposals
Purpose
The purpose of a DingoDB Improvement Proposal (DIP) is to introduce any major change into DingoDB. 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 DIP?
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:
- Data types
- SQL
- REST endpoints
- Data passed between backend and frontend
- Configuration
- Command line tools and arguments
What should be included in a DIP?
A DIP 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. 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;
- 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 DIP?
Anyone can initiate a DIP, but preferably someone with the intention of implementing it.
Process
- Create an issue with the prefix “[DIP]” in the title. The issue will be tagged as “dip” by a committer, and the title will be updated with the current DIP number.
- Notify the dingodb@zetyun mailing list that the DIP has been created, use the subject line [DISCUSS] DIP-0 DingoDB Improvement Proposals, the body of the email should look something like Please discuss & subscribe here: #1
- When writing the issue, fill in the sections as described above in “What should be included in a DIP?”. You can use the template included at the end of this document.
- A committer will initiate the discussion, and ensure that there’s enough time to analyze the proposal. Before accepting the DIP, a committer should call for a vote, requiring 3 votes and no vetoes from committers. Votes are timebox at 1 week, and conducted through email (with the subject [VOTE]).
- Create a pull request implementing the DIP, and referencing the issue.
Template
[DIP] 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 sub modules.
New dependencies
Describe any 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.