RFR: Initial section on testing [v3]

[Jesper Wilhelmsson]

On Mon, 19 Oct 2020 21:04:57 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Although I understand the desire to have as much relative information in the guide, I don't think we need to repeat
>> ourselves, most of the information presented here is already available in `doc/testing.md` and
>> `doc/hotspot-unit-tests.md`. the former document provides more comprehensive documentation about all
>> available/supported testing in OpenJDK, different modes of test execution; the latter gives an overview of different
>> `TEST*` macros available in hotspot gtest, defines _good_ tests, provides guidelines on writing such tests, etc.  I
>> think we need to find some middle ground here, so we won't duplicate documentation and at the same time, we won't force
>> people to gather required information from N different places. With that in mind, I think it's important to 1st define
>> the goal of 'testing' section of the Guide.
>
>> Although I understand the desire to have as much relative information in the guide, I don't think we need to repeat
>> ourselves, most of the information presented here is already available in `doc/testing.md` and
>> `doc/hotspot-unit-tests.md`. the former document provides more comprehensive documentation about all
>> available/supported testing in OpenJDK, different modes of test execution; the latter gives an overview of different
>> `TEST*` macros available in hotspot gtest, defines _good_ tests, provides guidelines on writing such tests, etc.  I
>> think we need to find some middle ground here, so we won't duplicate documentation and at the same time, we won't force
>> people to gather required information from N different places. With that in mind, I think it's important to 1st define
>> the goal of 'testing' section of the Guide.
> 
> The documents in /doc/ requires prior knowledge to understand. Those aren't written for beginners. The goal for the
> guide in this case is to provide quick links to more information and serve as a buffer to fill in the gaps for a first
> time tester.  I agree that we should avoid duplication. For the Developers' Guide I want to have just enough
> information to get everything up and running. For any additional information there should be links to more detailed
> documentation.  Personally I have issues with documentation that requires knowledge not only to understand, but also to
> access. But as the source is now on GitHub and the .md files are reasonably readable through the web interface it's at
> least possible to link to them. I don't know if search engines will index the JDK source code though so for people
> googling for documentation we still need some indexed document that refers to these documents.

> Besides the logistical information, I think it would be helpful to add
> some conceptual information about JDK testing.

Yes, I think this is a good idea. There is some of this in /doc/hotspot-unit-tests.md but it's GTest specific and very
HotSpot centric, so we should have something that is more generic and suitable for all. I have updated with a few
sentences about this. Let me know if you think this needs to be expanded more or have any other suggestions.

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

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