This page describes the Paimon Improvement Proposal (PIP) process for proposing a major change to Paimon.

To create your own PIP, click on "Create" on the header and choose "PIP-Template" other than "Blank page".


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

What is considered a "major change" that needs a PIP?

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:

  • Programing API
  • Classes marked with the @Public annotation
  • Storage binary formats
  • Configuration settings
  • Exposed monitoring information

What should be included in a PIP?

A PIP 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.
  • Migration Plan and Compatibility: 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.


Here is the process for making a PIP:

  1. Create a page which is a child of this one. Take the next available PIP number (below) and give your proposal a descriptive heading. If you don't have the necessary permissions for creating a new page, please ask on the development mailing list.
  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] PIP-{your PIP number} {your PIP heading} The discussion should happen on the mailing list not on the wiki since the 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 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 committers or PMC members) and no binding vetoes.
  5. Please update the PIP wiki page to reflect the current stage of the PIP after a vote. This acts as the permanent record indicating the result of the PIP (e.g., Accepted or Rejected). Also report the result of the PIP vote to the voting thread on the mailing list so the conclusion is clear.

Additional Information

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

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

Reference: Flink Improvement Proposals

  • No labels