Hour, Minute and Second are all read-only - so how do I change them?
You don’t. Instead you create a new Date value with the different hour/minute/second. You can do this using the Constructor or by using the DateInterval class.
I still havent quite wrapped my head around why this was necessary either. but then I never ran into any of the problems with the old class that this was supposed to fix.
OK - I knew I would get to this point at some time - and this is the time… I have never used/worked with Constructors. Can you please give me a quick syntax example of what your suggestion above would look like.
There are examples on the Xojo.Core.Date page in the Dev Center. A Constructor is what is called when you use New:
// Get a date an hour from now
Dim interval As New Xojo.Core.DateInterval
interval.Hours = 1
Dim future As Xojo.Core.Date = Xojo.Core.Date.Now + intervalAs for why this changed, this is explained in the Date section of the Migrating to the New Framework page.
It mostly boils down to date and time being annoyingly complicated topics. Adding “one hour, two seconds” can be different than “increment the hour by one and then increment the seconds by two”.
How?
Daylight time is enormously entertaining in this fashion 
Think about daylight saving.
If you have a date var with a time of 02:22:22 and you want to add 1 hour and 2 seconds, but it just so happens that at 03:00 on the given date the “clocks go back” by an hour, the result should be 02:22:24 in the non DST version of the timezone (northern hemisphere recently did this on various dates).
02:22:22 BST + 01:00:02 => 02:22:24 GMT
Not (02 + 01) : (22 + 00) : (22 + 02) = 03:22:24
going on & off dst is just bizarre
When you go onto daylight there is no 2 AM since it instantly jumps to 3 AM at the last moment after 1:59:59 am (at least in canada & the usa)
And when you fall back it has 1 am twice (once normal then at the last moment after 1:59:59 am it reverts to 1 am again)
Such joy
A pita for sure but you can use UTC/GMT internally for storing, calculating etc. No DST there.
For presentation, convert to local time. Not sure about the new framework but (if I remember correctly) with the old one you can add date.gmtoffset.
the old date has no notion of locale
so questions like “is dst in effect on this date ?” are a real pain to figure out
Since ICU is whats used date & time are
scalar value that indicates a specific point in time, independent of calendar system and local time zone. It is stored as the number of milliseconds from a reference point known as the epoch. The epoch is midnight Universal Time Coordinated (UTC) January 1, 1970 A.D. Negative UDate values indicate times before the epoch.
see http://userguide.icu-project.org/datetime
Back at WWDC 2011, Apple had a really good talk about performing calendar calculations that went into edge cases. There’s also a great video on the problem with time and timezones by Tom Scott, which is a bit shorter and entertaining.
The very short version of things is that there are enough edge cases to make a chainsaw. Leaving calendrical calculations to the framework is a good thing (and the framework leaves it to the OS).