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