Sure, I can see the value of putting it in the template to encourage thinking about it. Sounds good to me.
On Thu, Jan 31, 2019 at 2:47 PM Jonathan Wei <jon...@apache.org> wrote: > 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 > > > >> > > > > > > > > > >
