RFR: Initial section on testing [v6]

[Jesper Wilhelmsson]

On Thu, 22 Oct 2020 21:12:42 GMT, Igor Ignatyev <iignatyev at openjdk.org> wrote:

> Unfortunately, any useful documentation will become tied to a specific version, and the Guide already is: you refer to a specific directory layout, the layouts are different in different versions of JDK, tip vs 8u vs 11u;

I assume that you refer to "Code Owners" here. Actually that list is the union of all directories from JDK 9 and forward. Obviously I might have missed some directory that existed for some time in between, but that should be considered a bug. The intention is to cover all versions. Due to the large difference I didn't include JDK 8 and earlier. Maybe that's a bug as well, but my guess is that anyone working on JDK 8 these days already know who owns the code.

> the list of supported test harnesses is version-dependent; even recommendations and some of the best practices are version-dependent; as the presence and content of `/doc`;

If there are significant differences that is relevant to a large part of the community I think we should mention these differences. The Guide isn't only for developers of mainline. Please also note that the fact that these differences aren't mentioned today isn't because the Guide is version specific but rather because we are currently writing it and large parts of it is still missing.

> ... thus, according to your logic, the Guide must be in `/doc`, which, I guess, would make it harder "to find documentation on-line".

Having the Guide in `/doc` wouldn't make sense at all even if it was version specific since part of the Guide is trying to explain where to find he source code and how to download it. As you know, this part currently don't describe mainline since it was written in 2012 and hasn't been updated since.

> Actually, I have a slightly different opinion on the whole hypothesis where people expect to find documentation these days. Although it's true for in general people do that online, the information in this Guide and the other related documentation isn't generic information, it's the information for developers. From my experience, most developers expect to find all the needed documentation within their local workspace, not on some _external_ sources. This isn't to say that hosting the same (or similar) documentation on web-servers is useless, it's just not the 1st place I and, I believe, many others would start their search.

Ok. I have a different experience and can only speak for myself. In other open source projects I've looked at I've always used regular web search to find documentation, and so far I haven't seen any project where that documentation wasn't available in a nicely formatted on-line document. Maybe that says more about what kinds of projects I've been looking at rather than where projects in general keep their source code.

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

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