As confusing as this is, I agree with Tristan! :-)
----- Original Message -----
From: "Tristan Tarrant" <ttarrant(a)redhat.com>
To: "infinispan -Dev List" <infinispan-dev(a)lists.jboss.org>, "Jiri
Holusa" <jholusa(a)redhat.com>
Sent: Friday, May 5, 2017 11:12:31 AM
Subject: Re: [infinispan-dev] Documentation code snippets
+1 for #2 from me too
Tristan
On 5/5/17 4:43 PM, Jiri Holusa wrote:
> Hi Sebastian,
>
> yes, you're right. I think the best way would be to go with option 2 making
> it comprehensive, clean and transparent. I will issue another preview PR
> soon that would contain some part from Hot Rod Client, ISPN Serven and
> Embedded mode snippets making it as an example, what it would look like in
> the end.
>
> If anybody else has other opinions, please jump in, thanks.
> Jiri
>
>
> ----- Original Message -----
>> From: "Sebastian Laskawiec" <slaskawi(a)redhat.com>
>> To: "infinispan -Dev List" <infinispan-dev(a)lists.jboss.org>
>> Sent: Friday, May 5, 2017 3:48:43 PM
>> Subject: Re: [infinispan-dev] Documentation code snippets
>>
>> 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/t...
>>
>> On Wed, May 3, 2017 at 3:20 PM Jiri Holusa < jholusa(a)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_...
>>
>>
>>
>> ----- Forwarded Message -----
>>> From: "Jiri Holusa" < jholusa(a)redhat.com >
>>> To: "infinispan-internal" < infinispan-internal(a)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/do...
>>> [2]
>>>
https://github.com/hibernate/hibernate-orm/blob/master/documentation/src/...
>>>
>>>
>> _______________________________________________
>> infinispan-dev mailing list
>> infinispan-dev(a)lists.jboss.org
>>
https://lists.jboss.org/mailman/listinfo/infinispan-dev
>> --
>>
>>
>> SEBASTIAN ŁASKAWIEC
>>
>> INFINISPAN DEVELOPER
>>
>> Red Hat EMEA
>>
>> _______________________________________________
>> infinispan-dev mailing list
>> infinispan-dev(a)lists.jboss.org
>>
https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
> _______________________________________________
> infinispan-dev mailing list
> infinispan-dev(a)lists.jboss.org
>
https://lists.jboss.org/mailman/listinfo/infinispan-dev
>
--
Tristan Tarrant
Infinispan Lead
JBoss, a division of Red Hat
_______________________________________________
infinispan-dev mailing list
infinispan-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/infinispan-dev