With two patches, we'll need a two-phase commit to maintain consistency, and we all know what a PITA this can be. (Sorry, couldn't resist the pun. Carry on.)
On Thu, Oct 23, 2014 at 10:32 AM, Jay Kreps <jay.kr...@gmail.com> wrote: > That makes sense. I agree that moving to another doc system isn't a high > priority (it isn't as much work as it sounds because the HTML can all > remain as is, just the includes would get converted). But actually I don't > think that having a patch for docs and a patch for the code is too big a > hurdle either. I think maybe we should just start asking for documentation > patches and describe that in the contributing section--likely most people > just don't think of it. > > -Jay > > On Thu, Oct 23, 2014 at 7:16 AM, Joe Stein <joe.st...@stealth.ly> wrote: > >> I like how we have things in SVN. My issue is having two patches from >> contributors (one for tests + code and another for docs) that I am trying >> to solve. >> >> If we copy the entire SVN docs directory into git under /docs then >> contributions can patch the docs in their git patch. Committers can do 1 >> commit. >> >> When we release we just cp -r docs/* /svn/ && svn add * && svn co >> "release" //or such. The only trick is that we have to make sure for live >> website fixes that we commit in two places (but only then instead of every >> time). I don't mind doing something more fancy and generate the docs from >> some markdown but I am not sure it is necessary... we have a lot to get >> done in the next few months with 0.9 and I don't want to add anything >> unnecessary to that effort. >> >> I do think though with all the changes coming we want code contributors to >> keep the docs up to date and have doc changes + code + test all in one git >> patch would be best for everyone (however we accomplish that) for reviewing >> and such. >> >> /******************************************* >> Joe Stein >> Founder, Principal Consultant >> Big Data Open Source Security LLC >> http://www.stealth.ly >> Twitter: @allthingshadoop <http://www.twitter.com/allthingshadoop> >> ********************************************/ >> >> On Wed, Oct 22, 2014 at 1:53 PM, Jay Kreps <jay.kr...@gmail.com> wrote: >> >> > Currently we are handling the versioning problem by explicitly versioning >> > docs that change over time (configuration, quickstart, design, etc). This >> > is done by just creating a copy of these pages for each release in a >> > subdirectory. So we can commit documentation changes at any time for the >> > future release we just don't link up that release until it is out >> > (theoretically you could get there by guessing the url, but that is >> okay). >> > Although having multiple copies of certain pages, one for each release, >> > seems odd, I think it is actually better because in practice we often end >> > up editing old releases when we find problems in the older docs. >> > >> > -Jay >> > >> > On Wed, Oct 22, 2014 at 10:35 AM, Jarek Jarcec Cecho <jar...@apache.org> >> > wrote: >> > >> > > I would strongly support this idea. We have similar model in all other >> > > projects where I’m involved: >> > > >> > > The docs are part of the usual code base and we do require contributors >> > to >> > > update them when they are adding a new feature. And then during release >> > > time we simply take snapshot of the docs and upload them to our public >> > > webpages. This enables us to have simple versioned docs on the website, >> > so >> > > that users can easily find docs for their version and also the public >> > site >> > > do not contain docs of unreleased features :) There is a lot of ways >> how >> > to >> > > achieve that - in Sqoop 1 we used asciidoc to build the site, in Sqoop >> > > 2/Flume we’re using sphinx, Oozie is using markdown wiki... >> > > >> > > Jarcec >> > > >> > > > On Oct 22, 2014, at 10:27 AM, Jay Kreps <jay.kr...@gmail.com> wrote: >> > > > >> > > > Hey Joe, >> > > > >> > > > I'd love to encourage documentation contributions. >> > > > >> > > > I think we do have a way to contribute to docs. The current workflow >> > for >> > > > contributing is >> > > > 1. Checkout the docs >> > > > 2. Change docs >> > > > 3. Submit patch in normal way >> > > > 4. Committer reviews and applies >> > > > >> > > > For committers we have traditionally made the review step optional >> for >> > > docs. >> > > > >> > > > In reality this skips step 1.5 which is fiddling with apache for an >> > hour >> > > to >> > > > figure out how to get it to make apache includes work so you can see >> > the >> > > > docs. I actually think this is the bigger barrier to doc changes. >> > > > >> > > > One thing we could do is move the docs to one of the static site >> > > generators >> > > > to do the includes (e.g. Jekyll) this might make setup slightly >> easier >> > > > (although then you need to install Jekyll...). >> > > > >> > > > -Jay >> > > > >> > > > On Wed, Oct 22, 2014 at 9:55 AM, Joe Stein <joe.st...@stealth.ly> >> > wrote: >> > > > >> > > >> This comes up a lot but in reality not enough. We don't have a >> great >> > > way >> > > >> for folks to modify the code and change (or add) to the >> > documentation. I >> > > >> think the documentation is awesome and as we grow the code >> > contributors >> > > >> that should continue with them too. >> > > >> >> > > >> One thought I had that would work is that we copy the SVN files >> into a >> > > >> /docs folder in git. We can then take patches in git and then apply >> > > them >> > > >> to SVN when appropriate (like during a release or for immediate >> > fixes). >> > > >> This way code changes in that patch can have documentation changes. >> > The >> > > >> committers can manage what is changed where as appropriate either >> > prior >> > > to >> > > >> a release or live updates to the website. Yes/No? >> > > >> >> > > >> Thanks! >> > > >> >> > > >> /******************************************* >> > > >> Joe Stein >> > > >> Founder, Principal Consultant >> > > >> Big Data Open Source Security LLC >> > > >> http://www.stealth.ly >> > > >> Twitter: @allthingshadoop <http://www.twitter.com/allthingshadoop> >> > > >> ********************************************/ >> > > >> >> > > >> > > >> > >>
