Summary
The NiFi Improvement Proposal Process provides a formal set of steps for introducing significant structural changes. Creating a maintainable architecture with clear compatibility expectations is foundational to the health and growth of the project. The proposal format and review process outline the content and steps required for making substantial changes to project interfaces and capabilities.
Process Scope
The NiFi Improvement Proposal Process covers significant structural or directional changes to the project in several important areas.
- NiFi API module interfaces and classes supporting extensions
- nifi-api module
- NiFi Framework API module interfaces and classes supporting framework extensions
- nifi-framework-api module
- NiFi REST API services
- nifi-web-api Resource Classes define REST API methods
- NiFi Configuration Files
- bootstrap.conf
- nifi.properties
- authorizers.xml
- login-identity-providers.xml
- state-management.xml
Improvement Proposals may grow out of Jira issues depending on the scope of work described.
Project committers and PMC members should defer to using NiFi Improvement Proposals when the scope of Jira issues impacts one or more of the structural areas listed. The NIP Process is not designed to replace standard issue handling, but it can also provide a method to build consensus for a particular approach even when changes would not necessarily fit into existing categories.
Proposal Requirements
NiFi Improvement Proposals must include required sections for considerations.
- Title
- Motivation
- Scope
- Compatibility
- Description
- Verification
- Alternatives
The Title of a proposal should summarize the primary feature or change presented for consideration.
The Motivation of a proposal should include a description of the benefits or intended use cases of the changed described. A clear motivation helps evaluate the other aspects of the proposal as it allows project members to consider the goals together with the implementation details.
The Scope of a proposal is essential to evaluating implications of new features or breaking changes. The scope section should describe the key project modules that would be changed, whether extension interfaces, framework interfaces, or other public-facing features.
The Compatibility section of a proposal should indicate whether the changes may require a new major version, such as breaking backward compatibility with public interfaces. Breaking compatibility may highlight the need to introduce a migration strategy.
The Description section contains the a substantive implementation strategy. The description should be detailed enough to understand the core components, configuration properties, and integration points involved. Details may include interface definitions, pseudo code, or diagrams as necessary, depending on the complexity of the proposal.
The Verification section should provide a basic strategy for evaluating the proposed changes. This may include unit tests for self-contained changes, integration tests for cross-cutting features, or manual verification for environment-specific scenarios.
The Alternatives section is important as it relates to scope and compatibility considerations. Describing other approaches helps to avoid unnecessary reconsideration in the future, and also shows adequate attention given to the positives and negatives of various approaches.
Review Platform
Apache Jira provides self-service issue handling to support proposal review. NiFi Improvement Proposals have a separate Jira Project Key for identification and linking.
Jira issue comments support discussion of the proposal, and issue status indicates the intermediate or final status of a proposal.
Issue comments can be used for voting following the standard Apache Voting Process.
Review Process
Participation in the NiFi Improvement Proposal Process is open, with different project roles having different privileges.
Drafting
Committers and Project Management Committee Members can initiate a NiFi Improvement Proposal. Creation of a NiFi Improvement Proposal requires an author and a sponsor with project membership, which can be the same person.
Structural changes and adjustments to public interfaces involve a level of familiarity with project mechanics. Community contributors may submit Jira issues that necessitate a NiFi Improvement Proposal, but it is the privilege and responsibility of a committer or PMC member to author and sponsor a NIP.
Discussion
Following the pattern of code changes and releases, discussion on a NIP takes place in an open forum where anyone interested or involved with the project may provide feedback.
Voting
Voting on a NIP is open to any contributor, but PMC members cast binding votes and have the ability to veto.
Committers cast non-binding votes, but provide helpful feedback through the voting process.
Voting occurs over a period of 72 hours in most cases.
The sponsor tabulates the votes and announces the results.
Implementation
The sponsor is responsible for creating one or more issues referencing an approved NIP. Issue handling and pull request reviews for implementation follow standard project procedures.