Hey Vlad, slightly related and just in case you are not aware of this feature yet: You can include (parts of) actual source code files straight into AsciiDoc documents. We do that in the HV reference guide, e.g. at [1]. That way you are 100% sure your examples actually compile (and pass tests) and you don't need to copy & paste them.
Cheers, --Gunnar [1] https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch11.asciidoc 2016-01-13 15:30 GMT+01:00 Vlad Mihalcea <mihalcea.v...@gmail.com>: > Hi Steve, > > The User Guide illustrations are snippets of code that go into the extras > folder, which stays right next to every chapter. > That's in the main folder. > > The tests are now located in the test folder of the documentation folder, so > that we can update/evolve them in future. > They are also a proof that the code snippets work. > There was a time when I realized that an example was not really ok, and I > had to change that. > I change the test first to see how it worked, and only then I updated the > Guide. > They are also a form of regression testing, so that we are alerted if some > future change will break the expectations we made while writing the > documentation code snippets. > > The reader can fork the repo and try them, if he wishes. > > Vlad > > On Wed, Jan 13, 2016 at 4:12 PM, Steve Ebersole <st...@hibernate.org> wrote: >> >> Vlad, I see you created a PR for moving your new tests out of >> hibernate-entitymanager into documentation. I guess that depends on the >> intent. Are they meant as illustrations? And if so, how are you >> expecting >> people will see them? And if they are meant as real tests rather than as >> illustrations, I think moving them is not appropriate. >> >> On Tue, Jan 12, 2016 at 4:57 AM andrea boriero <drebor...@gmail.com> >> wrote: >> >> > I'm not against the use of Java 8 letting AnimalSniffer guarding for >> > compatibility, >> > but I understand this can cause some problems so I'm ok with removing >> > Java >> > 8 usage from tests. >> > >> > On 12 January 2016 at 10:07, Gunnar Morling <gun...@hibernate.org> >> > wrote: >> > >> > > @Vlad, what Java 8 syntax specifically are you using in the user guide >> > > tests (examples?)? >> > > >> > > I like the idea of using a current syntax in usage examples, to give >> > > the guide a current look and show that our APIs play well with current >> > > Java versions (while staying compatible with older ones). >> > > >> > > >> > > >> > > 2016-01-12 10:51 GMT+01:00 Sanne Grinovero <sa...@hibernate.org>: >> > > > +1 for Vlad's proposal to use the same JDK for tests and main code >> > > > in >> > > > a given module. >> > > > >> > > > Infinispan requires Java8 at runtime too, so that module should be >> > > > the >> > > > only one to use Java8? >> > > > >> > > > On 12 January 2016 at 07:55, Vlad Mihalcea <mihalcea.v...@gmail.com> >> > > wrote: >> > > >> I used Java 8 syntax in the User Guide tests as I remembered that >> > tests >> > > can >> > > >> use it, but I also agree that this is a rather strange move. >> > > >> Since we need to support Java 1.6, maybe it's a better idea to use >> > > >> the >> > > >> latest JDK just in the modules where we have no other choice. >> > > >> For testing, I think that 1.6 is just fine and I could easily >> > > >> change >> > > those >> > > >> tests to remove the 1.8 dependency. >> > > >> >> > > >> So I vote for using the same JDK for both main and test in a >> > particular >> > > >> module. >> > > >> >> > > >> Vlad >> > > >> >> > > >> On Mon, Jan 11, 2016 at 11:35 PM, Steve Ebersole >> > > >> <st...@hibernate.org >> > > >> > > >> wrote: >> > > >> >> > > >>> The former. People commit things that already assume the move to >> > Java >> > > 8 >> > > >>> locally to build (and test). But at the moment we have not >> > formalized >> > > >>> that, and so that causes problems when we import into an IDE - the >> > > imported >> > > >>> IDE project is built for 1.6 compliance and so everything we try >> > > >>> in >> > > the IDE >> > > >>> fails. >> > > >>> >> > > >>> On Mon, Jan 11, 2016 at 3:33 PM Gunnar Morling >> > > >>> <gun...@hibernate.org >> > > >> > > >>> wrote: >> > > >>> >> > > >>> > Hey, >> > > >>> > >> > > >>> > > or we move to Java 8 and rely on >> > > >>> > > AnimalSniffer to make sure we are still compatible. >> > > >>> > >> > > >>> > WDYM by "move to Java8" exactly? Requiring it at Hibernate's >> > > >>> > build >> > > >>> > time, or also at runtime in user apps? >> > > >>> > >> > > >>> > >> > > >>> > 2016-01-11 19:49 GMT+01:00 Steve Ebersole <st...@hibernate.org>: >> > > >>> > > The use of Java 8 features in Hibernate ORM is starting to >> > expand. >> > > >>> > Luckily >> > > >>> > > it is still constrained to just tests. >> > > >>> > > >> > > >>> > > However these usages make development in an IDE more and more >> > > >>> difficult. >> > > >>> > > Previously this was isolated to hibernate-infinispan. Now[1] >> > this >> > > has >> > > >>> > > crept into hibernate-entitymanager. We need to have a plan >> > > >>> > > here. >> > > >>> Either >> > > >>> > > we stop using Java 8 anywhere, or we move to Java 8 and rely >> > > >>> > > on >> > > >>> > > AnimalSniffer to make sure we are still compatible. >> > > >>> > > >> > > >>> > > Votes? Other options? >> > > >>> > > >> > > >>> > > [1] >> > > >>> > > >> > > >>> > >> > > >>> >> > > >> > >> > https://github.com/hibernate/hibernate-orm/commit/c2ece0108ed52d5e3a227ed0150cfb5cb1a76101 >> > > >>> > > _______________________________________________ >> > > >>> > > hibernate-dev mailing list >> > > >>> > > hibernate-dev@lists.jboss.org >> > > >>> > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > > >>> > >> > > >>> _______________________________________________ >> > > >>> hibernate-dev mailing list >> > > >>> hibernate-dev@lists.jboss.org >> > > >>> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > > >>> >> > > >> _______________________________________________ >> > > >> hibernate-dev mailing list >> > > >> hibernate-dev@lists.jboss.org >> > > >> https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > > > _______________________________________________ >> > > > hibernate-dev mailing list >> > > > hibernate-dev@lists.jboss.org >> > > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > > _______________________________________________ >> > > hibernate-dev mailing list >> > > hibernate-dev@lists.jboss.org >> > > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > > >> > _______________________________________________ >> > hibernate-dev mailing list >> > hibernate-dev@lists.jboss.org >> > https://lists.jboss.org/mailman/listinfo/hibernate-dev >> > >> _______________________________________________ >> hibernate-dev mailing list >> hibernate-dev@lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hibernate-dev > > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
