That structure sounds good: - expanding rejected alternatives to a broader rationale section sounds good - I like "operational impact" as suggested by Slim and Gian more than the corresponding KIP terminology - Future work is a good addition
For test plan, I don't have a very strong opinion on this, but I'm thinking it could make sense as an optional section (if someone has one, that's cool, if not, that's cool too, but perhaps having it present in the template would encourage ppl to think about testing strategies early on if they aren't already) On Thu, Jan 31, 2019 at 2:17 PM Jihoon Son <jihoon...@apache.org> wrote: > Thanks Gian. > The suggested template looks good to me. > > Jihoon > > On Thu, Jan 31, 2019 at 9:27 AM Gian Merlino <g...@apache.org> wrote: > > > 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 <g...@apache.org> 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 <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 > > >> > > > > > >
