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