RFR: Initial section on testing [v6]

Thu Oct 22 19:46:21 UTC 2020

On Thu, 22 Oct 2020 19:31:44 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Hi Igor,
>> 
>>> On Oct 22, 2020, at 12:31 PM, Igor Ignatev <notifications at github.com> wrote:
>>> 
>>> 
>>> Mailing list message from Lance Andersen <mailto:LANCE.ANDERSEN at ORACLE.COM> on guide-dev <mailto:guide-dev at openjdk.java.net>:
>>> 
>>> Understand, and I guess my point was should the use of TEST.properties be covered in the dev guide of just left to the JTREG pages. It would be nice to have best practices flushed out.
>>> 
>>> Best
>>> Lance
>>> 
>>> Hi Lance,
>>> 
>>> I agree that we need to write down the best practices and have them easily available and discoverable, but I don't think that the Guide is the right place for them. I see the Guide as a QuickStart or How To Start Hacking OpenJDK In 5 Minutes (as opposed to The Comprehension OpenJDK Guide: How To Do All Possible Things Right And What Things Not To Do). if we start to add all best practices to the guide, inevitably they will either be superficially covered or we end up with lots of information and overwhelm readers, both cases will result in poor comprehension and I'd argue would undermine the purpose of this document and will cause more confusion.
>>> 
>>> so I'd prefer not to cover TEST.properties here, instead, I suggest creating a ticket to document common best practices in /doc/jtreg-tests.md in the jdk repo, and list TEST.properties as one of the things we need to document.
>>> 
>>> 
>> Having an additional best practices document would be fine also and perhaps the dev guide just points to it.  I do think we need this as this will help with bringing new developers up to speed quicker as we all have a lot of information that we have learned over the years but it is not written down :-)
>> 
>> 
>> Best
>> Lance
>>> Cheers,
>>> -- Igor
>>> 
>>> —
>>> You are receiving this because you commented.
>>> Reply to this email directly, view it on GitHub <https://github.com/openjdk/guide/pull/30#issuecomment-714612515>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABQPFO2XCJGC6AZF7SRDK2TSMBM5PANCNFSM4STQRI7A>.
>>> 
>> 
>> 
>> Best
>> Lance
>> ------------------
>> 
>> 
>> 
>> 
>> Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
>> Oracle Java Engineering 
>> 1 Network Drive 
>> Burlington, MA 01803
>> Lance.Andersen at oracle.com
>
>> I agree that we need to write down the best practices and have them easily available and discoverable, but I don't think that the Guide is the right place for them. I see the Guide as a QuickStart or How To Start Hacking OpenJDK In 5 Minutes (as opposed to The Comprehension OpenJDK Guide: How To Do All Possible Things Right And What Things Not To Do). if we start to add all best practices to the guide, inevitably they will either be superficially covered or we end up with lots of information and overwhelm readers, both cases will result in poor comprehension and I'd argue would undermine the purpose of this document and will cause more confusion.
> 
> The Guide is intended to cover best practices so I think this is the best place for such documentation. In my opinion only docs that are tied to a specific version of the source code should be in the /doc/ directory. That is not the place for generic guides and documentation. Erik's comments above shows the problem with accessing that documentation - how do we link to it and how do we make it readable without requiring people to download and build the JDK? People expect to find documentation on-line these days.
> 
> Wether it's overwhelming or comprehensible is a matter of layout. Even large amounts of information can be made easily accessible with the right layout. I have planned to add a "Quick links"-box at the top of each section, with the relevant links for expert users who just want to get to the technical documentation. In a similar fashion we can have a "Pro-tip" box with some of the more advanced guidelines that might not be relevant for the beginner. It's not a problem to have a lot of text in the Guide as long as it's easily navigateable - and I'm pretty sure most people these days navigate using the search function in their browser.
> 
> The JTReg documentation is documentation for the tool and should not contain OpenJDK specific guidelines. Adding another document seems to me to be a step in the wrong direction. We already have too many different documents and nobody can find any information. We need to consolidate and reduce the number of places, not add more.

Hi  Jesper,

I am of your mindset on this, but will defer to the groups decision.

> On Oct 22, 2020, at 3:31 PM, Jesper Wilhelmsson <notifications at github.com> wrote:
> 
> 
> Having an additional best practices document would be fine also and perhaps the dev guide just points to it.
> 
> The Guide is intended to cover best practices so I think this is the best place for such documentation. In my opinion only docs that are tied to a specific version of the source code should be in the /doc/ directory. That is not the place for generic guides and documentation. Erik's comments above shows the problem with accessing that documentation - how do we link to it and how do we make it readable without requiring people to download and build the JDK? People expect to find documentation on-line these days.
> 
> Wether it's overwhelming or comprehensible is a matter of layout. Even large amounts of information can be made easily accessible with the right layout. I have planned to add a "Quick links"-box at the top of each section, with the relevant links for expert users who just want to get to the technical documentation. In a similar fashion we can have a "Pro-tip" box with some of the more advanced guidelines that might not be relevant for the beginner. It's not a problem to have a lot of text in the Guide as long as it's easily navigateable - and I'm pretty sure most people these days navigate using the search function in their browser.
> 
> The JTReg documentation is documentation for the tool and should not contain OpenJDK specific guidelines. Adding another document seems to me to be a step in the wrong direction. We already have too many different documents and nobody can find any information. We need to consolidate and reduce the number of places, not add more.
> 
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub <https://github.com/openjdk/guide/pull/30#issuecomment-714714124>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABQPFOZTPK3PYKXIIAUN4ODSMCCC7ANCNFSM4STQRI7A>.
> 

My best,
Lance
--
Lance Andersen
USTA EMA President and CEO
PTR Professional 5A
USPTA Elite Professional
TIA Global Cardio Tennis-Master Trainer
USRSA
Mobile: 978 857-0446
luckydogtennis.com -- luckydogtennis.com/TennisBlog -- cardiotennis.com

-------------

PR: https://git.openjdk.java.net/guide/pull/30