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 > >>> >> > >>> > > >>> > > >>> > >> > >> > > >
