Hi, Joe, Since you added the signing part, is it possible to make it off by default (instead of having people do "-x signArchives")?
Thanks, Jun On Mon, Sep 1, 2014 at 10:20 AM, Jay Kreps <jay.kr...@gmail.com> wrote: > Hey Bill, > > Thanks for this very useful list. > > I think part of the problem is this. We have started versioning our > documentation with each release. We do this to ensure people on older > releases can still see the documentation. In the latest release we > migrated a bunch of stuff off the wiki to help it stay versioned with > the main docs--that was why you were seeing some content on the wiki > and some on the main site. So the older version of the docs point to > the wiki, and the newer docs are in html. Unfortunately Google isn't > very smart about this, and may well choose the top hit to be the doc > from the older release (similar thing happens with jdk javadocs). > > Here are some things I think we could do: > 1. Yes, in general we are keeping things in site docs rather than > wiki. The reason to retain the wiki version is so the docs on the > older version remain complete. > 2. Quickstart: you are using the 0.8.0 quickstart. It works with 0.8.0 > but some details have changed for 0.8.1.1 (cli options, build > commands, etc). > 3. Ditto here. Good call on the projects page--looks like Jun fixed that. > 4. Oops, looks like Jun filed a JIRA for that. > 5. For Java 8, can you file a JIRA and include what you did and > whatever went wrong for you? > 6. Jun, can we default to not signing? That might be more intuitive... > 7. Can you elaborate on the javaapi coverage? I think you are saying > that the documentation is incomplete? > 8. Good point, that is a bug. Filed KAFKA-1621 for it. > > Each of the suggestions you made would be very useful, it would be > great if you would be willing to help us improve those things. > > -Jay > > On Sat, Aug 30, 2014 at 5:53 AM, Bill de hÓra <b...@dehora.net> wrote: > > Hi, > > > > On twitter recently [1] I said I'd send on a list of things that made > > getting 0.8 setup for a quick bench awkward. Individually they're all > minor > > and I apologize if this seem like nitpicking. But in sum, getting through > > them was a bit of a chore; it took maybe just short of a couple of hours > and > > a strong cup of coffee get to log stream nirvana :) > > > > Anyway, here's a list of things that tripped me up - > > > > - It seems like the 0.8 docs are in transition, or old docs have been > > abandoned. There is some information on cwiki.apache.org and some on > > kafka.apache.org. When I searched it was hit and miss which I landed on. > > > > - The quickstart on cwiki.apache.org looks very wrong. It still shows > sbt, > > but the project builds with gradle, the kafka-create-topic.sh params are > > wrong, the producer example's Partitioner has a generic param but > > Partitioner in the code doesn't have one, etc. > > > > - Some stuff on kafka.apache org also looked wrong, eg creating topics > in > > https://kafka.apache.org/08/quickstart.html, broken link to > > http://kafka.apache.org/projects.html, the link back to the code > example on > > cwiki. > > > > - The Kafka 0.8 binaries ship with perf scripts, but not perf lib. > > > > - A download for the perf lib wasn't anywhere I could see on the site > > (http://kafka.apache.org/downloads.html) - you'd have to know to search > > maven, or checkout Kafka and build it, and then put the jar into the lib > > area. > > > > - The project doesn't work/build with java 8 afaict, or didn't for me; > > there didn't seem to be a way to know that in advance. > > > > - The project trunk failed to build due to some signing/license checks > > (the diff I used to get things to build is here: > > https://gist.github.com/dehora/7e3c0bd75bb2b5d87557). > > > > - The javaapi coverage is partial. Initially I wasn't sure if I had > failed > > to import things from the right package before realizing I was looking at > > bad docs. > > > > - The messages flag on the perf script is required but not marked as > > required. > > > > > > In terms of what might help others, and I'd be happy to pitch in if > people > > thought they would make things easier, here's another list - > > > > - Have working code examples for 0.8, and mention StringEncoder in the > > docs for serializer.class. > > > > - Delete wrong information. It seems like there should be just one > > doc/wiki site and that cwiki.apache.org could be removed or marked dead > in > > big friendly letters. > > > > - Ship the perf jar with the binary, or, remove the perf scripts and > > create a separate perf distributable. > > > > - Make the build work out of the box. It seems like the lic/singing > checks > > are for publication rather than local dev. (I haven't tried the > instructions > > to setup in an IDE yet). > > > > Bill > > > > [1] https://twitter.com/dehora/status/503207180544520193 >
