Cool, I'll go ahead and make a template based on the previous discussion. Thanks, Jon
On Tue, Feb 12, 2019 at 9:16 AM Slim Bouguerra <bs...@apache.org> wrote: > @Gian All the above looks good to me. > I think having a template will tremendously help current devs and new > contributors, and will have a tremendous effect on the project ! > Thanks > > On Tue, Feb 12, 2019 at 9:00 AM Gian Merlino <g...@apache.org> wrote: > > > Does anyone have thoughts on the above suggestions? > > > > On Fri, Feb 1, 2019 at 2:16 PM Gian Merlino <g...@apache.org> wrote: > > > > > I think we should clarify the process too. Might I suggest, > > > > > > 1) Add a GitHub issue template with proposal headers and some > description > > > of what each section should be, so people can fill them in easily. > > > 2) Suggest that for any change that would need a design review per > > > http://druid.io/community/, the author also creates a proposal issue > > > following that template. It can be very short if the change is simple. > > The > > > design discussion should take place on the proposal issue, and the code > > > review should take place on the PR. A +1 on either the issue or the PR > > > would be considered a +1 for the design, while only a +1 on the PR > would > > be > > > considered a +1 for the code itself. > > > 3) Update http://druid.io/community/ and our CONTRIBUTING.md with > > > guidance about (2) and encouraging that the proposal issues are created > > > early in the dev cycle. > > > > > > I am thinking of "suggest" rather than "require" in (2) so we can start > > > slow and see how we like this process before making it mandatory. > > > > > > On Fri, Feb 1, 2019 at 2:22 AM Clint Wylie <clint.wy...@imply.io> > wrote: > > > > > >> +1 for proposal template. > > >> > > >> Do we also need to clarify the process that goes along with the > > proposals? > > >> (It seems clear to me we've reached consensus in wanting a proposal > > >> process, but less clear if we have a clear picture of or have reached > > >> consensus on the process itself). Things like when voting happens, > > >> appropriate PR timing, voting period, announcements to dev list, > > >> significance of silence (implicit +1 or -1?), etc. Even if just > adapting > > >> Kafka's I think it might be a good idea to lay it out in this thread. > > >> > > >> Beyond putting reference to this stuff in top level github readme and > on > > >> the website, is there anything more we should do to guide people that > > are > > >> thinking about contributing to use the proposal process? > > >> > > >> 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 > > >> > > > >> > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > > > > >
