If it's not clear - I am agreeing with Jihoon and Slim that a separate "Rationale" section makes sense in addition to a couple other suggested tweaks.
On Wed, Jan 30, 2019 at 3:46 PM Gian Merlino <[email protected]> wrote: > 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 <[email protected]> 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 >> >
