I think it'd also be nice to tweak a couple parts of the KIP template (Motivation; Public Interfaces; Proposed Changes; Compatibility, Deprecation, and Migration Plan; Test Plan; Rejected Alternatives). A couple people have suggested adding a "Rationale" section, how about adding that and removing "Rejected alternatives" -- rolling them in together? And dropping "test plan", since IMO that discussion can be deferred to the PR itself, when there is code ready. Finally, adding "future work", detailing where this change might lead us.
So in particular the template I am suggesting would be something like this. 1) Motivation: A description of the problem. 2) Proposed changes: Should usually be the longest section. Should include any changes that are proposed to user-facing interfaces (configuration parameters, JSON query/ingest specs, SQL language, emitted metrics, and so on). 3) Rationale: A discussion of why this particular solution is the best one. One good way to approach this is to discuss other alternative solutions that you considered and decided against. This should also include a discussion of any specific benefits or drawbacks you are aware of. 4) Operational impact: Is anything going to be deprecated or removed by this change? Is there a migration path that cluster operators need to be aware of? Will there be any effect on the ability to do a rolling upgrade, or to do a rolling _downgrade_ if an operator wants to switch back to a previous version? 5) Future work: A discussion of things that you believe are out of scope for the particular proposal but would be nice follow-ups. It helps show where a particular change could be leading us. There isn't any commitment that the proposal author will actually work on this stuff. It is okay if this section is empty. On Wed, Jan 30, 2019 at 3:14 PM Jihoon Son <jihoon...@apache.org> wrote: > Thanks Eyal and Jon for starting the discussion about making a template! > > The KIP template looks good, but I would like to add one more. > The current template is: > > - Motivation > - Public Interfaces > - Proposed Changes > - Compatibility, Deprecation, and Migration Plan > - Test Plan > - Rejected Alternatives > > It includes almost everything required for proposals, but I think it's > missing why the author chose the proposed changes. > So, I think it would be great if we can add 'Rationale' or 'Expected > benefits and drawbacks'. > People might include it by themselves in 'Motivation' or 'Proposed > Changes', but it would be good if there's an explicit section to describe > it. > > Best, > Jihoon >
