Redefine civil.md

[jodastephen]

Attempt to more fully explain why Local is the right choice - though this style of document isn't a great way to do so.

[ryzokuken]

@pipobscure @mj1856 @sffc your take on this?

[pipobscure]

Local comes from Latin locus "a place, spot, position," from Old Latin locus, literally "where something is placed”.

So while I empathise, it literally is the single quality civil objects don’t have.

As to the airline example: that’s the exact opposite of why the pilot says “local time will be...” he says that specifically to indicate that the time on the ground in that specific location may be different to what a passenger may have on their watch.

In short this has just proven why Local is exactly the wrong prefix.

[jodastephen]

In computing, we often name things based on what they have so I understand why people find this naming hard (eg. List and LinkedList). Instead, the naming choice of "local" here is about matching use by non-programmers - common parlance.

When I ask "what is your local time", the answer is "6pm". It is not "6pm in New York". Sure, the context of the question implied a location, but the answer did not include that location. The context is external and implied. It is the answer to the question that is being modelled here - not the question nor the context.

[domenic]

Agreed. A "local date/time" is a date/time that works and can be used locally. It is not a date/time that has a location. (That would be "DateTimeWithLocation", or "LocalizedDateTime", or, as this proposal calls it, "ZonedDateTime".)

For my part I don't really care about this prefix, but I have found the arguments of the form "LocalDateTimes don't have a location and therefore it's a bad name" to be kind of missing the point.

[sffc]

One potential point of confusion for developers is that we don't want to conflate "local" with "locale" (as in internationalization). In the absence of strong motivation, I would rather avoid using any variant of that word (local, localized, etc.) to mean anything other than i18n.

[sffc]

Thanks for the PR. In general though, we should update this document still with the assumption that we are moving forward with the Civil prefix. This PR is not the right place to make a case to change the prefix; please use #33 for that.

[sffc]

Please revert the title change.

[sffc]

Please keep these with the Civil prefix

[sffc]

If you add this line, please include citations and examples.

[sffc]

The language "But surely this misunderstands" is too strong. Please soften up the new material you added in this bullet.

[sffc]

Why is this a con? The fact that non-native English speakers are less likely to recognize this word means that they may read the documentation more closely and learn the concept correctly, rather than relying on false presumptions (such as assuming local implies locality).

[gilmoreorless]

This PR is not the right place to make a case to change the prefix; please use #33 for that.

@jodastephen was explicitly asked in #33 (comment) to make this PR:

Could you please make a PR against civil.md documenting your thoughts so everyone could see more clearly what was missing and perhaps move forward and make a better choice?

Now he's being told that he shouldn't have made the PR. As someone from outside the TC39 world, I'm finding it really confusing to know how to contribute to this proposal. There are many mixed messages being delivered.

[ryzokuken]

@gilmoreorless sorry, this is just a case of lack of communication between me and @sffc

Shane, I requested them to make a PR with their thoughts precisely so that we could discuss and scrutinize the arguments made in a productive manner since the discussion on #33 wasn't exactly going places. Since you've already posted your opinions on their arguments, I guess this seems to be working as expected.

[sffc]

Is the intention to merge this PR or to keep it open indefinitely for discussion? I reviewed this PR last night with the intention of eventually merging it.

[ryzokuken]

Yes, the intention is to merge it after comments have been addressed but also to mainly to have a place to document the criticisms to the civil prefix.

[sffc]

@jodastephen, can you address my review feedback? Then we can merge this PR. Thank you 😄

[pipobscure]

In short, I severely disagree with using the Local prefix. In fact my experience with other APIs leads me to be fairly firm here, since the Local prefix is one of the things that are confusing. (I'll leave this as pure opinion here, since that's largely what it is, albeit one founded on long experience.)

I'll try to take a new train of thought here:

• We seem to be moving toward not using modules, since modules seem to not move sufficiently quickly
• Consequently we are working toward a namespace object on the global.
• I'd name this global property Temporal
• Which would mean that the temporal objects, would be properties of this Temporal object
• In turn you'd refer to them from ES as Temporal.Instant for example
• Which means they already have a prefix of a kind
• So why not just have:
  • Temporal.Instant
  • Temporal.ZonedDateTime
  • Temporal.OffsetDateTime
  • Temporal.DateTime
  • Temporal.Date
  • Temporal.Time

In short we could eliminate this entire discussion by simply dropping the prefix entirely if we use the Temporal global as a prefix. This seems acceptable since in the context of a module the usual pattern would be:

import { Date } from 'std:temporal';
const date = new Date(1976, 11, 18); // November 18th 1976

which would be confusing since

const date = new Date(1976, 11, 18); // December 18th 1976

However using a global namespace object the pattern would be:

const date = new Temporal.Date(1976, 11, 18); // November 18th 1976
const legacy = new Date(1976, 11, 18); // December 18th 1976

which seems pretty clear.

---

Any case: I don't think this is mergable without further debate.

[pipobscure]

Based on the love shown, I have updated the polyfill. We'll go with the Temporal namespace object instead.

[jodastephen]

Base on the love shown

Hmm. 4 likes compared to 18 for LocalDate?

I've not responded to the PR because it seemed fairly pointless for me to do so. The file civil.md is a classic "winners" document - it outlines the position of the winner in the debate and aims to denigrate the alternatives. Having such a document isn't a bad thing to record a decision, but it is not a great place to start when trying to debate.

Since writing the PR I contacted someone I know in Google. Apparently, the term "civil date" has been widely pushed within Google by the authors of the Abseil C++ library (which is a Google authored library). Those Googlers suggesting C++ Abseil as a reference should be clear as to the connection given the strong link between Abseil and Google. The naming discussion should not IMO be based solely on the opinion of Google's internal naming choices.

I will say that Temporal.Date is better than CivilDate, SimpleDate, PlainDate or any of the other suggested prefixes I've heard. I can't say that I think it will make the API popular as it is quite long, and dot-separated types are not generally for primary concepts IMO. I think there is another problem too - Temporal.DateTime is fundamentally confusing. If you look at the names of the types in the API you would assume that DateTime is the main class, whereas it is in fact a local date-time, which is one of the least useful types when writing applications. The use of a common prefix Local is specifically to contrast the types to the Offset and Zoned prefixes. Losing that is a loss when trying to understand the API.

Having done some research in my email history, the naming discussions for JSR-310 happened in October and November 2007 (unfortunately lost to the internet, though I have a copy personally). Most of the suggestions that have come up here were considered along with a few others: OnlyDate\OnlyTime\OnlyDateTime, WallTime\CalendarDate\CalendarDateTime and DateYMD\TimeOfDay\DateYMDTime .

The result that Local was adopted. In addition to ISO-8601, RFC2445 was referenced as a precedent, which exactly describes "local time":

The date with local time form is simply a date-time value that does not contain the UTC designator nor does it reference a time zone. ... Date-time values of this type are said to be "floating" and are not bound to any time zone in particular.

In summary, LocalDate is a really well established name at this point and widely used, in libraries and in both specifications.

[pipobscure]

Thanks for the information!

I hadn't even known about the whole Google naming angle (I'm with Bloomberg).

You are correct in civil.md being a winners document. We've had this discussion 3 times already and resolved it 3 times in favour of Civil. And this is just the fourth iteration of that discussion.

That of course indicated to me that Civil is not the right answer. Whence the call to simply omit any prefix and just put them all into the Temporal namespace object.

In terms of using Local as a prefix, I admit a lot of bias here. The problem is exactly that it is so wide-spread. In fact it's so wide-spread that there is a lot of conflict of what it means:

• PHP/Perl/C - localtime gives you the time at the current location
• Java/RFC2445 = LocalDate, LocalTime, LocalDateTime are timezone independent

I have been around for a while, and have never met a programmer that intuitively understood what LocalDate actually means and what's the difference to LocaleDate or anything else. So while there might be ample precedent, there are many bad things in the world that have ample precedent and I consider this to be one of those bad things.

I do agree with you that Civil has insufficient support as does Simple. The few times I asked people to explain what Local actually meant in the issues here, I got examples that were exactly wrong. So let's try and see what this looks like without any prefixes and just a namespace object.

Here is the way I'm thinking about using this:

const { Date, Time, DateTime, ZonedDateTime } = Temporal;
...

I'm also about to add the following:

const { Local } = Temporal;
Local.timeZone(); // a TimeZone object containing the system time-zone
Local.instant(); // current moment as an Instant
Local.date(); // a Date object having the current date
Local.time(); // a Time object having the current time
Local.dateTime(); // a DateTime object having the current date & time
Local.zonedDateTime(); // a ZonedDateTime object representing the current time

In the end I think this will make working with the object fairly easy. Especially since the withXXX() methods all accept plain JS objects with the relevant fields (and not just actual Temporal objects). So in effect:

const lunch = Local.date().withTime({ hour: 12 });

With that, I hope you'll give me the time to update all the documents and documentation and release the polyfill to npm again to allow actually playing with it and exploring whether this actually works.

Cheers, Philipp

P.S.: Once the documents have all been updated, I of course welcome the debate to reopen.

[jodastephen]

A quick comment - I think Date and Time are OK as type names as they can't be confused and can easily enough be linked with LocalDate/LocalTime in other libraries. The main reason against them in Java and JavaScript is history, which you may have a solution to (I'm not a JS coder).

However, I think DateTime would be a mistake. There may be a way out by prefixing just DateTime. Thus you'd have Date, Time and LocalDateTime, which would connect the API to other libraries. It might also be possible to consider UnzonedDateTime as actual usage of the type would be limited and it is very explicit, so the negativeness of the name "unzoned" would be limited.

[ljharb]

@pipobscure note that adding any way in Temporal to get the current date or time will create strong objections from some committee members; I'd suggest getting consensus on such a change before making it.

[pipobscure]

@ljharb I’m aware. Which is why I did it in a way/place that is easy to remove/secure. I’ll mention it in context with SES in documentation and during the update.

[gilmoreorless]

Here is the way I'm thinking about using this:

const { Date, Time, DateTime, ZonedDateTime } = Temporal;
...

@pipobscure I agree with using a Temporal namespace. But doesn't that destructuring example directly contradict your reasoning for not using a built-in module earlier in the thread?

[...] in the context of a module the usual pattern would be:

import { Date } from 'std:temporal';
const date = new Date(1976, 11, 18); // November 18th 1976

which would be confusing since

const date = new Date(1976, 11, 18); // December 18th 1976

However using a global namespace object the pattern would be:

const date = new Temporal.Date(1976, 11, 18); // November 18th 1976
const legacy = new Date(1976, 11, 18); // December 18th 1976

which seems pretty clear.

I don't see how one is any more or less confusing than the other:

const { Date } = Temporal
// vs.
import { Date } from 'std:temporal'