Hi All, Can we finalize the approach? So that we can proceed further.
1. Gwen's suggestion + existing svn repo 2. Gwen's suggestion + new git repo for docs kumar On Thu, Aug 20, 2015 at 11:48 PM, Manikumar Reddy <ku...@nmsworks.co.in> wrote: > Also can we migrate svn repo to git repo? This will help us to fix > occasional doc changes/bug fixes through github PR. > > On Thu, Aug 20, 2015 at 4:04 AM, Guozhang Wang <wangg...@gmail.com> wrote: > >> Gwen: I remembered it wrong. We would not need another round of voting. >> >> On Wed, Aug 19, 2015 at 3:06 PM, Gwen Shapira <g...@confluent.io> wrote: >> >> > Looking back at this thread, the +1 mention "same repo", so I'm not >> sure a >> > new vote is required. >> > >> > On Wed, Aug 19, 2015 at 3:00 PM, Guozhang Wang <wangg...@gmail.com> >> wrote: >> > >> > > So I think we have two different approaches here. The original >> proposal >> > > from Aseem is to move website from SVN to a separate Git repo, and >> hence >> > > have separate commits on code / doc changes. For that we have >> accumulated >> > > enough binging +1s to move on; Gwen's proposal is to move website into >> > the >> > > same repo under a different folder. If people feel they prefer this >> over >> > > the previous approach I would like to call for another round of >> voting. >> > > >> > > Guozhang >> > > >> > > On Wed, Aug 19, 2015 at 10:24 AM, Ashish <paliwalash...@gmail.com> >> > wrote: >> > > >> > > > +1 to what Gwen has suggested. This is what we follow in Flume. >> > > > >> > > > All the latest doc changes are in git, once ready you move changes >> to >> > > > svn to update website. >> > > > The only catch is, when you need to update specific changes to >> website >> > > > outside release cycle, need to be a bit careful :) >> > > > >> > > > On Wed, Aug 19, 2015 at 9:06 AM, Gwen Shapira <g...@confluent.io> >> > wrote: >> > > > > Yeah, so the way this works in few other projects I worked on is: >> > > > > >> > > > > * The code repo has a /docs directory with the latest revision of >> the >> > > > docs >> > > > > (not multiple versions, just one that matches the latest state of >> > code) >> > > > > * When you submit a patch that requires doc modification, you >> modify >> > > all >> > > > > relevant files in same patch and they get reviewed and committed >> > > together >> > > > > (ideally) >> > > > > * When we release, we copy the docs matching the release and >> commit >> > to >> > > > SVN >> > > > > website. We also do this occasionally to fix bugs in earlier docs. >> > > > > * Release artifacts include a copy of the docs >> > > > > >> > > > > Nice to have: >> > > > > * Docs are in Asciidoc and build generates the HTML. Asciidoc is >> > easier >> > > > to >> > > > > edit and review. >> > > > > >> > > > > I suggest a similar process for Kafka. >> > > > > >> > > > > On Wed, Aug 19, 2015 at 8:53 AM, Ismael Juma <ism...@juma.me.uk> >> > > wrote: >> > > > > >> > > > >> I should clarify: it's not possible unless we add an additional >> step >> > > > that >> > > > >> moves the docs from the code repo to the website repo. >> > > > >> >> > > > >> Ismael >> > > > >> >> > > > >> On Wed, Aug 19, 2015 at 4:42 PM, Ismael Juma <ism...@juma.me.uk> >> > > wrote: >> > > > >> >> > > > >> > Hi all, >> > > > >> > >> > > > >> > It looks like it's not feasible to update the code and website >> in >> > > the >> > > > >> same >> > > > >> > commit given existing limitations of the Apache infra: >> > > > >> > >> > > > >> > >> > > > >> > >> > > > >> >> > > > >> > > >> > >> https://issues.apache.org/jira/browse/INFRA-10143?focusedCommentId=14703175&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14703175 >> > > > >> > >> > > > >> > Best, >> > > > >> > Ismael >> > > > >> > >> > > > >> > On Wed, Aug 12, 2015 at 10:00 AM, Ismael Juma < >> ism...@juma.me.uk> >> > > > wrote: >> > > > >> > >> > > > >> >> Hi Gwen, >> > > > >> >> >> > > > >> >> I filed KAFKA-2425 as KAFKA-2364 is about improving the >> website >> > > > >> >> documentation. Aseem Bansal seemed interested in helping us >> with >> > > the >> > > > >> move >> > > > >> >> so I pinged him in the issue. >> > > > >> >> >> > > > >> >> Best, >> > > > >> >> Ismael >> > > > >> >> >> > > > >> >> On Wed, Aug 12, 2015 at 1:51 AM, Gwen Shapira < >> g...@confluent.io >> > > >> > > > >> wrote: >> > > > >> >> >> > > > >> >>> Ah, there is already a JIRA in the title. Never mind :) >> > > > >> >>> >> > > > >> >>> On Tue, Aug 11, 2015 at 5:51 PM, Gwen Shapira < >> > g...@confluent.io> >> > > > >> wrote: >> > > > >> >>> >> > > > >> >>> > The vote opened 5 days ago. I believe we can conclude with >> 3 >> > > > binding >> > > > >> >>> +1, 3 >> > > > >> >>> > non-binding +1 and no -1. >> > > > >> >>> > >> > > > >> >>> > Ismael, are you opening and JIRA and migrating? Or are we >> > > looking >> > > > >> for a >> > > > >> >>> > volunteer? >> > > > >> >>> > >> > > > >> >>> > On Tue, Aug 11, 2015 at 5:46 PM, Ashish Singh < >> > > > asi...@cloudera.com> >> > > > >> >>> wrote: >> > > > >> >>> > >> > > > >> >>> >> +1 on same repo. >> > > > >> >>> >> >> > > > >> >>> >> On Tue, Aug 11, 2015 at 12:21 PM, Edward Ribeiro < >> > > > >> >>> >> edward.ribe...@gmail.com> >> > > > >> >>> >> wrote: >> > > > >> >>> >> >> > > > >> >>> >> > +1. As soon as possible, please. :) >> > > > >> >>> >> > >> > > > >> >>> >> > On Sat, Aug 8, 2015 at 4:05 PM, Neha Narkhede < >> > > > n...@confluent.io> >> > > > >> >>> >> wrote: >> > > > >> >>> >> > >> > > > >> >>> >> > > +1 on the same repo for code and website. It helps to >> > keep >> > > > both >> > > > >> in >> > > > >> >>> >> sync. >> > > > >> >>> >> > > >> > > > >> >>> >> > > On Thu, Aug 6, 2015 at 1:52 PM, Grant Henke < >> > > > >> ghe...@cloudera.com> >> > > > >> >>> >> wrote: >> > > > >> >>> >> > > >> > > > >> >>> >> > > > +1 for the same repo. The closer docs can be to code >> > the >> > > > more >> > > > >> >>> >> accurate >> > > > >> >>> >> > > they >> > > > >> >>> >> > > > are likely to be. The same way we encourage unit >> tests >> > > for >> > > > a >> > > > >> new >> > > > >> >>> >> > > > feature/patch. Updating the docs can be the same. >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > If we follow Sqoop's process for example, how would >> > small >> > > > >> >>> >> > > > fixes/adjustments/additions to the live >> documentation >> > > occur >> > > > >> >>> without >> > > > >> >>> >> a >> > > > >> >>> >> > new >> > > > >> >>> >> > > > release? >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > On Thu, Aug 6, 2015 at 3:33 PM, Guozhang Wang < >> > > > >> >>> wangg...@gmail.com> >> > > > >> >>> >> > > wrote: >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > > I am +1 on same repo too. I think keeping one git >> > > > history of >> > > > >> >>> code >> > > > >> >>> >> / >> > > > >> >>> >> > doc >> > > > >> >>> >> > > > > change may actually be beneficial for this >> approach >> > as >> > > > well. >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > Guozhang >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > On Thu, Aug 6, 2015 at 9:16 AM, Gwen Shapira < >> > > > >> >>> g...@confluent.io> >> > > > >> >>> >> > > wrote: >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > > I prefer same repo for one-commit / >> lower-barrier >> > > > >> benefits. >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > Sqoop has the following process, which decouples >> > > > >> >>> documentation >> > > > >> >>> >> > > changes >> > > > >> >>> >> > > > > from >> > > > >> >>> >> > > > > > website changes: >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > 1. Code github repo contains a doc directory, >> with >> > > the >> > > > >> >>> >> > documentation >> > > > >> >>> >> > > > > > written and maintained in AsciiDoc. Only one >> > version >> > > of >> > > > >> the >> > > > >> >>> >> > > > > documentation, >> > > > >> >>> >> > > > > > since it is source controlled with the code. >> > (unlike >> > > > >> >>> current SVN >> > > > >> >>> >> > > where >> > > > >> >>> >> > > > we >> > > > >> >>> >> > > > > > have directories per version) >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > 2. Build process compiles the AsciiDoc to HTML >> and >> > > PDF >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > 3. When releasing, we post the documentation of >> the >> > > new >> > > > >> >>> release >> > > > >> >>> >> to >> > > > >> >>> >> > > the >> > > > >> >>> >> > > > > > website >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > Gwen >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > On Thu, Aug 6, 2015 at 12:20 AM, Ismael Juma < >> > > > >> >>> ism...@juma.me.uk >> > > > >> >>> >> > >> > > > >> >>> >> > > > wrote: >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > > > Hi, >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > For reference, here is the previous >> discussion on >> > > > moving >> > > > >> >>> the >> > > > >> >>> >> > > website >> > > > >> >>> >> > > > to >> > > > >> >>> >> > > > > > > Git: >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > http://search-hadoop.com/m/uyzND11JliU1E8QU92 >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > People were positive to the idea as Jay said. >> I >> > > would >> > > > >> >>> like to >> > > > >> >>> >> > see a >> > > > >> >>> >> > > > bit >> > > > >> >>> >> > > > > > of >> > > > >> >>> >> > > > > > > a discussion around whether the website >> should be >> > > > part >> > > > >> of >> > > > >> >>> the >> > > > >> >>> >> > same >> > > > >> >>> >> > > > repo >> > > > >> >>> >> > > > > > as >> > > > >> >>> >> > > > > > > the code or not. I'll get the ball rolling. >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > Pros for same repo: >> > > > >> >>> >> > > > > > > * One commit can update the code and website, >> > which >> > > > >> means: >> > > > >> >>> >> > > > > > > ** Lower barrier for updating docs along with >> > > > relevant >> > > > >> >>> code >> > > > >> >>> >> > changes >> > > > >> >>> >> > > > > > > ** Easier to require that both are updated at >> the >> > > > same >> > > > >> >>> time >> > > > >> >>> >> > > > > > > * More eyeballs on the website changes >> > > > >> >>> >> > > > > > > * Automatically branched with the relevant >> code >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > Pros for separate repo: >> > > > >> >>> >> > > > > > > * Potentially simpler for website-only changes >> > > > (smaller >> > > > >> >>> repo, >> > > > >> >>> >> > less >> > > > >> >>> >> > > > > > > verification needed) >> > > > >> >>> >> > > > > > > * Website changes don't "clutter" the code Git >> > > > history >> > > > >> >>> >> > > > > > > * No risk of website change affecting the code >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > Your thoughts, please. >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > Best, >> > > > >> >>> >> > > > > > > Ismael >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > On Fri, Jul 31, 2015 at 6:15 PM, Aseem Bansal >> < >> > > > >> >>> >> > > asmbans...@gmail.com> >> > > > >> >>> >> > > > > > > wrote: >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > > > Hi >> > > > >> >>> >> > > > > > > > >> > > > >> >>> >> > > > > > > > When discussing on KAFKA-2364 migrating docs >> > from >> > > > svn >> > > > >> >>> to git >> > > > >> >>> >> > came >> > > > >> >>> >> > > > up. >> > > > >> >>> >> > > > > > > That >> > > > >> >>> >> > > > > > > > would make contributing to docs much >> easier. I >> > > have >> > > > >> >>> >> contributed >> > > > >> >>> >> > > to >> > > > >> >>> >> > > > > > > > groovy/grails via github so I think having >> > mirror >> > > > on >> > > > >> >>> github >> > > > >> >>> >> > could >> > > > >> >>> >> > > > be >> > > > >> >>> >> > > > > > > > useful. >> > > > >> >>> >> > > > > > > > >> > > > >> >>> >> > > > > > > > Also I think unless there is some good >> reason >> > it >> > > > >> should >> > > > >> >>> be a >> > > > >> >>> >> > > > separate >> > > > >> >>> >> > > > > > > repo. >> > > > >> >>> >> > > > > > > > No need to mix docs and code. >> > > > >> >>> >> > > > > > > > >> > > > >> >>> >> > > > > > > > I can try that out. >> > > > >> >>> >> > > > > > > > >> > > > >> >>> >> > > > > > > > Thoughts? >> > > > >> >>> >> > > > > > > > >> > > > >> >>> >> > > > > > > >> > > > >> >>> >> > > > > > >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > > -- >> > > > >> >>> >> > > > > -- Guozhang >> > > > >> >>> >> > > > > >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > >> > > > >> >>> >> > > > -- >> > > > >> >>> >> > > > Grant Henke >> > > > >> >>> >> > > > Software Engineer | Cloudera >> > > > >> >>> >> > > > gr...@cloudera.com | twitter.com/gchenke | >> > > > >> >>> >> linkedin.com/in/granthenke >> > > > >> >>> >> > > > >> > > > >> >>> >> > > >> > > > >> >>> >> > > >> > > > >> >>> >> > > >> > > > >> >>> >> > > -- >> > > > >> >>> >> > > Thanks, >> > > > >> >>> >> > > Neha >> > > > >> >>> >> > > >> > > > >> >>> >> > >> > > > >> >>> >> >> > > > >> >>> >> >> > > > >> >>> >> >> > > > >> >>> >> -- >> > > > >> >>> >> >> > > > >> >>> >> Regards, >> > > > >> >>> >> Ashish >> > > > >> >>> >> >> > > > >> >>> > >> > > > >> >>> > >> > > > >> >>> >> > > > >> >> >> > > > >> >> >> > > > >> > >> > > > >> >> > > > >> > > > >> > > > >> > > > -- >> > > > thanks >> > > > ashish >> > > > >> > > > Blog: http://www.ashishpaliwal.com/blog >> > > > My Photo Galleries: http://www.pbase.com/ashishpaliwal >> > > > >> > > >> > > >> > > >> > > -- >> > > -- Guozhang >> > > >> > >> >> >> >> -- >> -- Guozhang >> > >
