Docs: Confusion in parse around YYYY vs yyyy

[tgriesser]

Hi all, great project.

I wanted to point out some behavior I found a bit confusing when checking out this library (specifically the latest 2.0.0-alpha.8).

ISO 8601 dates are generally referred to as YYYY-MM-DD. Here it is in the toISOString MDN docs. This is also the moment.js syntax for years, months, days.

However I was confused, when doing:

it('parses dates correctly', function () {
  var dateString = '2018-05-18';
  var formatString = `(see below)`
  var result = parse(dateString, formatString, new Date())
  assert.deepEqual(result.toISOString().slice(0, 10), "2018-05-18")
})

With YYYY-MM-DD we get 2017-01-18
With yyyy-MM-DD, yyyy-mm-dd and yyyy-mm-DD we seem to get 2018-01-18 (not sure why)
With yyyy-MM-dd we get the correct 2018-05-18

I did a little reading up on the specs to try to understand what was going on where / the difference between YYYY & yyyy. This is the best source I came across.

I'm not sure if there's anything to change here, other than to point out it can be very confusing for folks unfamiliar with the unicode format, and it'd be worth putting in bold somewhere that if you aren't sure, you probably don't want YYYY, as it's of little use outside of the context of weeks of a year, e.g. Week 1 of 2018.

A console warning might even be nice for YYYY-MM-DD specifically, as it's quite common elsewhere.

[kossnocorp]

Thank you for the feedback! That is a valid point, that's very confusing. We migrated to the Unicode format as we believe that is better to follow a standard rather than a convention used in a (currently) popular library.

[emilmork]

Glad I found this. Did not understand why parse('17.07.2018, 'DD.MM.YYY') gave me => 17.07.2017

[natecartwright]

This also causes an issue when needing to manually format a date with a format string to get it to display in ISO format. You need to now escape the literal "T" in the ISO string format by wrapping it in single quotes (to escape it).

Thus to get an ISO String out of format:

yyyy-MM-dd'T'HH:mm:ss.sssX

Edit: Would still be nice to have an 'ISO' format that spits out an ISO formatted string now that Unicode is what's used for format. The above is kinda messy. Yes, normally you'd want to just call .toISOFormat() but that's not possible with some React UI libraries, which only support a format string.

[kossnocorp]

There is what we're going to do to address the confusion about tokens:

• Collect popular tokens that confuse. YYYY and DD is a good start, what else?
• Throw a descriptive exception when a user tries to use those tokens in format and parse without passing a special option. The name is yet to figure, but it could be something like imAwareAboutUnicodeTokens. We'll keep it for a while and then remove it once the dust is settled up.
• Add a bold warning to the top of the format and parse docs with the description of the problem.
• Write a post with the reasoning behind the change and description of the problem.
• Print a message with a warning about breaking changes after date-fns@2 installation.

[kossnocorp]

Please see the PR that addresses the issue: #920