Taking inspiration from Apache Spark's improvement proposal guide,
The purpose of a SPIP is to inform and involve the user community in major improvements to the Spark codebase throughout the development process, to increase the likelihood that user needs are met.
This guideline should be used for significant user-facing or cross-cutting changes, not small incremental improvements. When in doubt, if a committer thinks a change needs a proposal, it does.
A GPIP is similar to a product requirement document commonly used in product management that must do the following,
Role | GPIP Task |
---|---|
Member | Discuss the changes for which a GPIP can be submitted or they can submit a GPIP directly |
Contributor | Other than Member tasks above, contributors can help with discussions regarding the technical feasibility of a GPIP |
Committer | Other than Contributor tasks above, committers can help with discussions regarding whether a GPIP aligns with long-term project goals, and by shepherding GPIPs |
Taking terms from the Apache Spark's improvement proposal guide,
Proposal Author
Any community member who authors an improvement proposal and is committed to pushing the change through the entire process. SPIP authorship can be transferred.
Proposal Shepherd
A PMC member who is committed to shepherding the proposed change throughout the entire process. Although the shepherd can delegate or work with other committers in the development process, the shepherd is ultimately responsible for the success or failure of the proposal.
Note: If a GPIP is too small/ incremental/ wide-scoped and should have been done through the normal JIRA process, a committer should remove the GPIP label and notify the author.
A GPIP document is a short document with a few questions, inspired by the Heilmeier Catechism:
- What are you trying to do? Articulate your objectives using absolutely no jargon.
- What problem is this proposal NOT designed to solve?
- How is it done today, and what are the limits of current practice?
- What is new in your approach and why do you think it will be successful?
- Who cares? If you are successful, what difference will it make?
- What are the risks?
- How long will it take?
- What are the mid-term and final “exams” to check for success?
Appendix A. Proposed API Changes. An Optional section defining APIs changes, if any. Backward and forward compatibility must be taken into account.
Appendix B. Optional Design Sketch: How are the goals going to be accomplished? Give sufficient technical detail to allow a contributor to judge whether it’s likely to be feasible. Note that this is not a full design document.
Appendix C. Optional Rejected Designs: What alternatives were considered? Why were they rejected? If no alternatives have been considered, the problem needs more thought.
Implementation should take place via the standard process for code changes. Changes that require GPIPs typically also require design documents to be written and reviewed.