+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
