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 >>>>>>> >>>>>>> >>>>>>> >>>>>>> >>>>>> >>>> >>>> >> >>
signature.asc
Description: Message signed with OpenPGP
