Page History

...

The purpose of FIPs is to have a central place to collect and document planned major enhancements to Fluss. While Github issue Issues is still the tool to track tasks, bugs, and progress, the FIPs give an accessible high level overview of the result of design discussions and proposals. Think of FIPs as collections of major design documents for user-relevant changes.

We want to make Fluss a core architectural component for users. Keeping this kind of usage health requires a high level of compatibility between releases — core architectural elements can't break compatibility or shift functionality from release to release. As a result, each new major feature or public api API has to be done in a way that we can stick with it going forward.

This means when making this kind of change, we need to think through what we are doing as best we can prior to release. And as we go forward we need to stick to our decisions as much as possible. All technical decisions have pros and cons, so it is important we capture the thought process that lead to a decision or design to avoid flip-flopping needlessly.

...

This process also isn't meant to discourage incompatible changes — proposing an incompatible change is totally legitimate. Sometimes we will have made a mistake and the best path forward is a clean break that cleans things up and gives us a good foundation going forward. Rather this is intended to avoid accidentally introducing half thought-out interfaces and protocols that cause needless heartburn when changed. Likewise the definition of "compatible" is itself squishy: small details like which errors are thrown when are clearly part of the contract but may need to change in some circumstances, likewise performance isn't part of the public contract but dramatic changes may break use cases. So we just need to use good judgement about how big the impact of an incompatibility will be and how big the payoff is.

What is

...

Considered a "

...

Major Change" That Needs a FIP?

Any of the following should be considered a major change:

...

All of the following are public interfaces that people build around:

• Binary logLog/kv KV format
• The network protocol and api API behavior
• Classes marked with the @Public annotation
• Configuration, especially client configuration
• Monitoring
• Command line tools and arguments

Not all compatibility commitments are the same. We need to spend significantly more time on logLog/kv KV format and protocol as these break code in lots of clients, cause downtime releases, etc. Public apis APIs are next as they cause people to rebuild code and lead to compatibility issues in large multi-dependency projects (which end up requiring multiple incompatible versions). Configuration, monitoring, and command line tools can be faster and looser — changes here will break monitoring dashboards and require a bit of care during upgrades but aren't a huge burden.

For the most part monitoring, command line tool changes, and configs are added with new features so these can be done with a single KIPFIP.

What

...

Should be

...

Included in a FIP?

A FIP should contain the following sections:

• Motivation: describe Describe the problem to be solved.
• Proposed Change: describe 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 Impact to any of the "compatibility commitments" described above. We want to call these out in particular so everyone thinks about them.
• Migration Plan and Compatibility: if If this feature requires additional support for a no-downtime upgrade describe how that will work.
• 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.

...

Process

Here is the process for making a FIP:

1. Create a new page.
   1. If you have permissions for creating a new page

...

1. 1. in Confluence, click on "Create" in the header and choose "FIP-Template" (and not "Blank page") to create your own FIP. Take the next available FIP number and give your proposal a descriptive

...

1. 1. title. e.g. "FIP-1: Fluss Lakehouse Storage Design". 
   2. If you don't have

...

1. 1. permissions for creating a new page,

...

1. 1. create a Google Doc and make that view-only. As a FIP number, please use FIP-XXX. 

...

1. 1. Post that Google Doc to the Dev mailing list for a discussion

...

1. 1. thread 

...

Process

Here is the process for making a FIP:

1. Follow the instructions at "Create your Own FIP".
2. Fill in the sections as described above
3. Start a [DISCUSS] thread on the Apache mailing list. Please ensure that the subject of the thread is of the format [DISCUSS] FIP-{your FIP number} {your FIP headingtitle} . The discussion should happen on the mailing list not on the wiki Wiki, since the wiki Wiki comment system doesn't work well for larger discussions. In the process of the discussion you may update the proposal. You should let people know the changes you are making.
4. Once the proposal is finalized and there are no more open discussions
   1. If your FIP is already in Confluence, proceed to step 5.
   2. If your FIP is in a Google Doc, please ask a committer/PMC on the Dev mailing list to copy the contents from your Google Doc to a FIP page , and to create a FIP number for you before proceeding to step 5. 
5. call Call a [VOTE] to have the proposal adopted. These proposals are more serious than code changes and more serious even than release votes.  Requires 3 binding +1 votes (From from committers or PMC members) and no binding vetoes.
6. Please update the FIP wiki Wiki page to reflect the current stage of the FIP after a vote. This acts as the permanent record indicating the result of the FIP (e.g., Accepted or Rejected). Also report the result of the FIP vote to the voting thread on the mailing list so the conclusion is clear.

Please don't forget to add a label to the FIP page with (one of "discussion", "accepted", "released", "rejected") to reflect the current stage of the FIP. The following is the example to add "discussion" label to the FIP page:

...

• The progress of a FIP should not be long blocked on an unresponsive reviewer. A reviewer who blocks a FIP with dissenting opinions should try to respond to the subsequent replies timely, or at least provide a reasonable estimated time to respond.
• A typical reasonable time to wait for responses is 1 week, but be pragmatic about it. Also, it would be considerate to wait longer during holiday seasons (e.g., Christmas, Chinese New Year, etc.).
• We encourage FIP proposers to actively reach out to the interested parties (e.g., previous contributors of the relevant part) early. It helps expose and address the potential dissenting opinions early, and also leaves more time for other parties to respond while the proposer works on the FIP.
• Committers should use their veto rights with care. According to the ASF policy, vetos vetoes must be provided with a technical justification showing why the change is bad. They should not be used for simply blocking the process so the voter has more time to catch up.

Additional Information

• A FIP is not necessarily the final solution, and the final solution and details may change with code reviewreviews. We should try our best to update the FIP and vote again.

• Not all code changes must wait for a FIP to vote complete. If there is no response from in the FIP thread, you can also start contributing code. However, please note that before starting to commit code, please notify in the PIP send a notification to the FIP discussion thread. If anyone is voted -1, please reach an agreement consensus in a timely manner.

Under

...

Discussion

...