Thank you for starting the discussion there. Matteo
On Mon, Jun 12, 2017 at 5:07 PM Dave Fisher <[email protected]> wrote: > Hi - > > > On Jun 12, 2017, at 4:59 PM, Matteo Merli <[email protected]> wrote: > > > > The documentations sources are in Markdown. From there, the proposed > > solution would be to use Jekill to generate HTML, plus a set of other > > scripts to automate the documentation for Javadoc, doxygen, REST API, CLI > > tools, protobuf definition, etc. > > > >> The Apache website infrastructure is hosted in SVN. > > > > Some time back I was reading that some project are using GIT based > > publishing. That would work by committing the "generated" static website > > into a "asf-site" branch in the project repository. > > I would prefer git to avoid dealing with multiple source control system, > > though it would not be a big problem in any case. > > > > https://blogs.apache.org/infra/entry/git_based_websites_available > > I’ve included you on an email to [email protected] to ask about the > status. This will naturally lead into discussions about GitHub transfer. > > Regards, > Dave > > > > > > > > On Mon, Jun 12, 2017 at 4:30 PM Dave Fisher <[email protected]> > wrote: > > > >> The Apache website infrastructure is hosted in SVN. There are certain > >> requirements for links. > >> > >> It would be good to discuss. For example is the content in Markdown, > XML, > >> HTML or what? It is not a big deal to conform. I have some experience > from > >> moving OpenOffice.org to Apache. > >> > >> Regards. > >> Dave > >> > >>> On Jun 12, 2017, at 4:21 PM, Matteo Merli <[email protected]> wrote: > >>> > >>>> The project will need to have a minimal website. > >>> > >>> A colleague of mine, a technical writer, is going through the existing > >>> documentation, editing, expanding it and re-organizing it a bit. He's > >> also > >>> setting up the script and tools to generate a static website with links > >> to > >>> each version documentation. > >>> > >>> A pull-request will be ready in the next few days. We were also waiting > >> for > >>> the repo to be moved over to the ASF before starting with the website > >>> (because some nomenclature will change, copyright noticies, etc..). > >>> > >>> > >>> On Mon, Jun 12, 2017 at 2:11 PM Dave Fisher <[email protected]> > >> wrote: > >>> > >>>> Hi - > >>>> > >>>> The project will need to have a minimal website. I would be willing to > >> be > >>>> the test case about documentation. If it is enough for me to > understand > >> how > >>>> to do development and use along with understanding the architecture > >> then it > >>>> will be good. > >>>> > >>>> I would recommend that a Wiki be used for shared design. There are > many > >>>> approaches and some choices for the Wiki. Apache offers Confluence and > >>>> MOIN. Then there is Github. I am familiar with Confluence, but don’t > let > >>>> that influence the project’s choice unduly. > >>>> > >>>> Here to help. > >>>> > >>>> Regards, > >>>> Dave > >>>> > >>>>> On Jun 12, 2017, at 12:55 PM, Matteo Merli <[email protected]> > >>>> wrote: > >>>>> > >>>>>> 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 > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>> > >>>> > >>>> > >> > >> > >
