> Is there specific criteria for determining whether documents are necessary or not?
That's a good question. I don't have a precise answer for it. As Andrews stated, it should allow any contributor to understand the new feature/changes, enough to be able to do a meaningful code review and also serve as design documentation for future contributors. So, if after the discussion, some details are changed, the wiki should be updated to reflect the final state. If one thinks that additional context is not required, he should go ahead with a PR. And later we can discuss whether a design doc for that change would be beneficial or not. For candidates, and to give an example, I was thinking to start with a "Pulsar native proxy" proposal that I'm working on. Also, I think other good candidates would be the non-persistent topics from Rajan, or the delivery throttling. On Thu, Jun 8, 2017 at 10:21 PM Sahaya Andrews <[email protected]> wrote: > On Thu, Jun 8, 2017 at 7:08 PM, Nozomi Kurihara <[email protected]> > wrote: > > Hi Matteo, > > > > ➢ The document doesn't need to be a super-detailed specification, but > should > > ➢ explain all the design points, reasons for choosing a determined > solution, > > ➢ rejected alternatives and allow for other contributors to > understand the > > ➢ feature/change and to contribute as well to it. > > ➢ > > I agree with creating such design documents in the Wiki. > > > > ➢ for large code changes (new features, improvements) > > ➢ > > Is there specific criteria for determining whether documents are > necessary or not? > > One way to approach is how quickly someone new can understand the > architecture or a feature, so they can contribute back. > > Coming up with a list of such modules/features is not difficult. > > Andrews. > > > > > Thanks, > > Nozomi Kurihara > > > > 2017/06/09 5:13 に、"Matteo Merli" <[email protected]> を書き込みました: > > > > So far the discussion for large code changes (new features, > improvements) > > in the project has happened in a very informal way. > > > > As a way to improve community involvement and also to have a better > > internal > > documentation I would like to propose to adopt the PIP model that > many > > projects > > follow. > > > > Here, PIP would stand for "Pulsar Improvement Proposal" and would > consist > > in creating design documents in the Wiki with a sequential id. > > > > The document doesn't need to be a super-detailed specification, but > should > > explain all the design points, reasons for choosing a determined > solution, > > rejected alternatives and allow for other contributors to understand > the > > feature/change and to contribute as well to it. > > > > The advantage would be to have a preliminary discussion and gather > feedback > > on the design itself and also have the proposals there as a > reference. > > > > In some cases the design has been discussed over "issues" or PRs but > then > > later it's more difficult to understand the whole picture, since the > > information is fragmented. > > > > Opinions? > > > > Matteo > > > > > > > > >
