Yeah that sounds good to me. That would involve someone converting us over to the templating system we chose (something like Jenkyll would be easy since it allows inline HTML, so we'd just have to replace the apache includes). It's also quite possible that Apache has solved the whole SVN/website dependency. I get the feeling git is no longer as taboo as it once was in Apache...
-Jay On Sat, Mar 28, 2015 at 9:46 PM, Gwen Shapira <gshap...@cloudera.com> wrote: > On Thu, Mar 26, 2015 at 9:46 PM, Jay Kreps <jay.kr...@gmail.com> wrote: > > The reason the docs are in svn is that when we were setting up the site > > apache required that to publish doc changes. Two possible fixes: > > 1. Follow up with infra to see if they have git integration working yet > > 2. Move to a model where doc "source" is kept in the main git and we use > > jenkyl or something like that to generate result html (i.e. with things > > like headers) and then check that in to svn to publish it. > > > > The second item would have the advantage of not needing to configure > apache > > includes to see the docs, but would likely trade it for jenkyl setup > stuff. > > Jenkyl might actually fix a lot of the repetitive stuff in the docs today > > (e.g. generating section numbers, adding <p> tags, etc). > > What we do at other projects that I'm familiar with (Sqoop, Flume) is > that we manage the docs "source" (i.e. asciidoc or similar) in git. > When its time to release a version (i.e. after a successful vote on > RC), we build the docs, manually copy to the SVN repo and push (or > whatever the SVN equivalent...). Its a bit of a manual pain, but its > only few times a year. This is also a good opportunity to upload > updated javadocs, docs generated from ConfigDef and KafkaMetrics, etc. > > Gwen > > > > > > -Jay > > > > On Thu, Mar 26, 2015 at 8:22 PM, Jiangjie Qin <j...@linkedin.com.invalid > > > > wrote: > > > >> > >> > >> On 3/26/15, 7:00 PM, "Neha Narkhede" <n...@confluent.io> wrote: > >> > >> >> > >> >> Much much easier to do this if the docs are in git and can be > reviewed > >> >>and > >> >> committed / reverted with the code (transactions makes > synchronization > >> >> easier...). > >> +1 on this, too! > >> > > >> > > >> >Huge +1. > >> > > >> >On Thu, Mar 26, 2015 at 6:54 PM, Joel Koshy <jjkosh...@gmail.com> > wrote: > >> > > >> >> +1 > >> >> > >> >> It is indeed too easy to forget and realize only much later that a > >> >> jira needed a doc update. So getting into the habit of asking "did > you > >> >> update the docs" as part of review will definitely help. > >> >> > >> >> On Thu, Mar 26, 2015 at 06:36:43PM -0700, Gwen Shapira wrote: > >> >> > I strongly support the goal of keeping docs and code in sync. > >> >> > > >> >> > Much much easier to do this if the docs are in git and can be > reviewed > >> >> and > >> >> > committed / reverted with the code (transactions makes > synchronization > >> >> > easier...). > >> >> > > >> >> > This will also allow us to: > >> >> > 1. Include the docs in the bits we release > >> >> > 2. On release, update the website with the docs from the specific > >> >>branch > >> >> > that was just released > >> >> > 3. Hook our build to ReadTheDocs and update the "trunk" docs with > >> >>every > >> >> > commit > >> >> > > >> >> > > >> >> > Tons of Apache projects do this already and having reviews enforce > the > >> >> "did > >> >> > you update the docs" before committing is the best way to guarantee > >> >> updated > >> >> > docs. > >> >> > > >> >> > Gwen > >> >> > > >> >> > On Thu, Mar 26, 2015 at 6:27 PM, Jun Rao <j...@confluent.io> wrote: > >> >> > > >> >> > > Hi, Everyone, > >> >> > > > >> >> > > Quite a few jiras these days require documentation changes (e.g., > >> >>wire > >> >> > > protocol, ZK layout, configs, jmx, etc). Historically, we have > been > >> >> > > updating the documentation just before we do a release. The > issue is > >> >> that > >> >> > > some of the changes will be missed since they were done a while > >> >>back. > >> >> > > Another way to do that is to keep the docs updated as we complete > >> >>each > >> >> > > jira. Currently, our documentations are in the following places. > >> >> > > > >> >> > > wire protocol: > >> >> > > > >> >> > > > >> >> > >> >> > >> > https://cwiki.apache.org/confluence/display/KAFKA/A+Guide+To+The+Kafka+Pr > >> >>otocol > >> >> > > ZK layout: > >> >> > > > >> >> > > > >> >> > >> >> > >> > https://cwiki.apache.org/confluence/display/KAFKA/Kafka+data+structures+i > >> >>n+Zookeeper > >> >> > > configs/jmx: https://svn.apache.org/repos/asf/kafka/site/083 > >> >> > > > >> >> > > We probably don't need to update configs already ported to > ConfigDef > >> >> since > >> >> > > they can be generated automatically. However, for the rest of the > >> >>doc > >> >> > > related changes, keeping they updated per jira seems a better > >> >>approach. > >> >> > > What do people think? > >> >> > > > >> >> > > Thanks, > >> >> > > > >> >> > > Jun > >> >> > > > >> >> > >> >> > >> > > >> > > >> >-- > >> >Thanks, > >> >Neha > >> > >> >
