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 >
