Hi Guozhang, Our plan is to follow Gwen's suggested approach and migrate the existing svn site repo to new git repo.
(1) Gwen's suggestion will help to us maintain latest docs in Kafka repo itself. We periodically need to copy these latest docs to site repo. I will submit patch for this. (2) svn repo -> git repo migration will help us to integrate site repo to git tooling/github. It will be easy to maintain the site repo and changes. So we have created new git repo for docs and need committer help to create a branch "asf-site". new git repo: https://git-wip-us.apache.org/repos/asf/kafka-site.git Hope this clears the confusion. Kumar I thought Gwen's suggestion was to us a separate folder in the same repo for docs instead of a separate branch, Gwen can correct me if I was wrong? Guozhang On Mon, Aug 24, 2015 at 10:31 AM, Manikumar Reddy <ku...@nmsworks.co.in> wrote: > Hi, > > Infra team created git repo for kafka site docs. > > Gwen/Guozhang, > Need your help to create a branch "asf-site" and copy the exiting > svn contents to that branch. > > git repo: https://git-wip-us.apache.org/repos/asf/kafka-site.git > > > https://issues.apache.org/jira/browse/INFRA-10143?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14709630#comment-14709630 > > Kumar > > On Fri, Aug 21, 2015 at 6:16 PM, Ismael Juma <ism...@juma.me.uk> wrote: > > > My preference would be to do `2` because it reduces the number of tools > we > > need to know. If we want to clone the repo for the generated site, we can > > use the same tools as we do for the code repo and we can watch for > changes > > on GitHub, etc. > > > > Ismael > > > > On Fri, Aug 21, 2015 at 1:34 PM, Manikumar Reddy <ku...@nmsworks.co.in> > > wrote: > > > > > 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 > > > >> > > > > > > > > > > > > > > -- -- Guozhang
