RFR: Initial section on testing [v6]

[Lance Andersen]

On Thu, 22 Oct 2020 19:43:24 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>>> 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

Works for me, thank you Jesper!

> On Oct 22, 2020, at 4:04 PM, Jesper Wilhelmsson <notifications at github.com> wrote:
> 
> 
> @JesperIRL commented on this pull request.
> 
> In src/index.md <https://github.com/openjdk/guide/pull/30#discussion_r510424425>:
> 
> > +
> +Below is a small example of a JTReg test. It’s a clean Java class with a main method that is called from the test harness. If the test fails we throw a RuntimeException. This is picked up by the harness and is reported as a test failure. Try to always write a meaningful message in the exception. One that actually helps with understanding what went wrong once the test fails.
> +
> +    /*
> +     * @test
> +     * @summary Make sure feature X handles Y correctly
> +     * @run main TestXY
> +     */
> +    public class TestXY {
> +        public static void main(String[] args) throws Exception {
> +            var result = X.y();
> +            if (result != expected_result) {
> +                throw new RuntimeException("X.y() gave " + result + ", expexted " + expected_result);
> +            }
> +        }
> +    }
> Let's agree on not adding anything about TEST.properties at this point. I have added a note in the todo-list about the need for documented best practices for this. Once the text is written we can discuss where to put it.
> 
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub <https://github.com/openjdk/guide/pull/30#discussion_r510424425>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABQPFO7VY2OXME3SM32KAIDSMCF6RANCNFSM4STQRI7A>.
> 

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