Hey Jiri, Very good investigation. I was all for option #2 (use existing testsuite) but now I'm leaning towards option #1 (separate testsuite).
I believe there are 3 main parts to be tested and synced with documentation - Hot Rod Client, Infinispan Server and Embedded Mode. The first two can be tested together I think. To some extend this is already implemented in ExampleConfigsIT [1]. The Embedded Mode is much harder to test in my opinion, since the tests are spread all around the repo. I guess this will be the main challenge of this task. Thanks, Sebastian [1] https://github.com/infinispan/infinispan/blob/master/server/integration/testsuite/src/test/java/org/infinispan/server/test/configs/ExampleConfigsIT.java On Wed, May 3, 2017 at 3:20 PM Jiri Holusa <jhol...@redhat.com> wrote: > Moving this to infinispan-dev. > > I've just issued a PR [1], where I setup the code snippets generation. It > was actually pretty easy. I started implementing it for the configuration > part of the documentation and I came across following findings/issues. > > There were more votes for option 2 (see the previous mail for detail, in > summary using existing testsuite), hence I started with that. Pretty > shortly I see following issues: > * XML configuration - since we want to have the <infinispan> element there > in the configuration, I have to do one XML file per one configuration code > snippet -> the number of files will grow and will mess up the "normal" > testsuite > * IMHO biggest problem - our testsuite is usually not written in > "documentation simplicity". For example, in testsuite we barely (= never) > do "EmbeddedCacheManager cacheManager = new DefaultCacheManager("...");", > we obtain the cache manager by some helper method. While this is great for > testing, you don't want to have this in documentation as it should be > simple and straightforward. Another example would be [2]. Look at the > programmatic configuration snippets. In the testsuite, we usually don't > have that trivial setup, not so comprehensively written somewhere. > * When you want to introduce a new code snippet, how can you be sure that > the snippet is not somewhere in the testsuite already, but written a bit > differently? I encountered this right from the beginning, search the test > classes and looking for "good enough" code snippet that I could use. > > Together it seems to me that it will mess up the testsuite quite a bit, > make the maintenance of documentation harder and will significantly prolong > the time needed for writing new documentation. What do you think? How about > we went the same way as Hibernate (option 1 in first email) - creating > separate documentation testsuite that is as simple as possible, descriptive > and straightforward. > > I don't really care, which option we choose, I will implement it either > way, but I wanted to show that there are some pitfalls of the option 2 as > well :( > > Cheers, > Jiri > > [1] https://github.com/infinispan/infinispan/pull/5115 > [2] > http://infinispan.org/docs/stable/user_guide/user_guide.html#configuring_caches_programmatically > > > > ----- Forwarded Message ----- > > From: "Jiri Holusa" <jhol...@redhat.com> > > To: "infinispan-internal" <infinispan-inter...@redhat.com> > > Sent: Friday, April 7, 2017 6:33:53 PM > > Subject: [infinispan-internal] Documentation code snippets > > > > Hi everybody, > > > > during the documentation review for JDG 7.1 GA, I came across this little > > thing. > > > > Having a good documentation is IMHO crucial for people to like our > technology > > and the key point is having code snippets in the documentation up to date > > and working. During review of my parts, I found out many and many > outdated > > code snippets, either non-compilable or using deprecated methods. I would > > like to eliminate this issue in the future, so it would make our > > documentation better and also remove burden when doing documentation > review. > > > > I did some research and I found out that Hibernate team (thanks Radim, > Sanne > > for the information) does a very cool thing and that is that the code > > snippets are taken right from testsuite. This way they know that the code > > snippet can always compile and also make sure that it's working > properly. I > > would definitely love to see the same in Infinispan. > > > > It works extremely simply that you mark by comment in the test the part, > you > > want to include in the documentation, see an example here for the > AsciiDoc > > part [1] and here for the test part [2]. There are two ways of how to > > organize that: > > 1) create a separate "documentation testsuite", with as simple as > possible > > test classes - Hibernate team does it this way. Pros: documentation is > > easily separated. Cons: possible duplication. > > 2) use existing testsuite, marking the parts in the existing testsuite. > Pros: > > no duplication. Cons: documentation snippets are spread all across the > > testsuite. > > > > I would definitely volunteer to make this happen in Infinispan > > documentation. > > > > What do you guys think about it? > > > > Cheers, > > Jiri > > > > [1] > > > https://raw.githubusercontent.com/hibernate/hibernate-validator/master/documentation/src/main/asciidoc/ch03.asciidoc > > [2] > > > https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/test/java/org/hibernate/userguide/caching/FirstLevelCacheTest.java > > > > > _______________________________________________ > infinispan-dev mailing list > infinispan-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/infinispan-dev > -- SEBASTIAN ĆASKAWIEC INFINISPAN DEVELOPER Red Hat EMEA <https://www.redhat.com/> <https://red.ht/sig>
_______________________________________________ infinispan-dev mailing list infinispan-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/infinispan-dev