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 > >> > > >
