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