Clarify dow and doy usage in locales

[mattjohnsonpint]

The only docs we have about dow and doy are in comments [here]:(http://momentjs.com/docs/#/i18n/locale-data/)

This should be clarified, as many of the locale files make the mistake of thinking that doy: 1 means that the week with Jan 1 is the first week.

[mattjohnsonpint]

This would prevent confusion such as that in moment/moment#3056 also.

[mattjohnsonpint]

There's more discussion in moment/moment#2115 about how doy should be calculated.

[maggiepint]

I'll get to it when I start my next round of documentation.
I honestly am not sure if I understand it, but I think if I debug through the code a few times I'll figure it out.

[usmonster]

I'd rather first update the logic to make it more intuitive, as suggested by @ichernev in moment/moment#2115. A mentioned on that issue, the current semantics are kind of an abuse of an early implementation and not very intuitive nor based on any standard implementation. :/

Question: Would that kind of backwards-compatible change require an [RFC](Moment RFCs)?

[usmonster]

[bump]

I'm still keen on updating the logic, though not sure I can do it in a backwards compatible way because of locale configurations such as { dow: 0, doy: 6} not having the same meaning before vs. the change.

I'd suggested an alternative on moment/moment#2115, but I think I need more feedback on how to continue. Not sure this is the right place to ask for that feedback, though.. Thoughts?

[pranjalk]

Hi!
I am fairly new to open source projects, and was looking at documentation issues seemed like a good place to start. Probably I can write up a small paragraph on how ISO week data works and that might help?

[usmonster]

Hi @pranjalk! I'd wait for feedback from the official project members, though this open issue is more about documenting proper usage of these specific configuration options, which may change depending on responses to my above questions.

The current semantics of doy aren't very meaningful to users and might need some changes before being documented.

[adamlibusa]

I would like to bump this. I would prefer an introduction to a semantically more meaningful setting variable and deprecating doy (as suggested here moment/moment#2115 (comment)), but even with the status quo, it should be better documented.

My suggestion would be to take Gregor Rayman's explanation as a basis (moment/moment#2115 (comment)). My proposal for the documentation:

Customizing Locale: 1st Day of Week & 1st Week of Year

To define the first day of week and the first week of year, customize the entry week:

week: {
    dow : 6, // Define on which day the week starts (0 - Sunday, 1 - Monday, ..., 6 - Saturday)
    doy : 12  // Define the first week of year 
}

doy is calculated as 7 + dow - janX, where janX is the x-th January that must belong to the week No. 1.

Three settings for the first day of week and the first week of year most used around the world:

ISO-8601: Europe

const week = {
    dow: 1,  // 1st day of week is Monday
    doy: 4  // 1st week of the year is the one that contains the first Thursday (7 + 1 - 4)
}

US, Canada:

const week = {
    dow: 0, // 1st day of week is Sunday
    doy: 6  // 1st week of the year is the one that contains the 1st of January (7 + 0 - 1)
}

Most of Arab countries:

const week = {
    dow: 6,  // 1st day of week is Saturday
    doy: 12  // 1st week of the year is the one that contains the 1st of January (7 + 6 - 1)
 }

[marwahaha]

@adamlibusa @pranjalk @usmonster - Documentation on existing behavior is best as a first pass.

Other discussions about changing behavior can be had in moment/moment.

[warrenwhipple]

I took a shot at turning @adamlibusa 's suggested text into a doc PR.

[marwahaha]

fixed in #513

[adamlibusa]

Thanks @mj1856 for bringing this up and @warrenwhipple for the PR!

[Hartaxfr]

I would like to bump this. I would prefer an introduction to a semantically more meaningful setting variable and deprecating doy (as suggested here moment/moment#2115 (comment)), but even with the status quo, it should be better documented.

My suggestion would be to take Gregor Rayman's explanation as a basis (moment/moment#2115 (comment)). My proposal for the documentation:

Customizing Locale: 1st Day of Week & 1st Week of Year

To define the first day of week and the first week of year, customize the entry week:

week: {
    dow : 6, // Define on which day the week starts (0 - Sunday, 1 - Monday, ..., 6 - Saturday)
    doy : 12  // Define the first week of year 
}

doy is calculated as 7 + dow - janX, where janX is the x-th January that must belong to the week No. 1.

Three settings for the first day of week and the first week of year most used around the world:

ISO-8601: Europe

const week = {
    dow: 1,  // 1st day of week is Monday
    doy: 4  // 1st week of the year is the one that contains the first Thursday (7 + 1 - 4)
}

US, Canada:

const week = {
    dow: 0, // 1st day of week is Sunday
    doy: 6  // 1st week of the year is the one that contains the 1st of January (7 + 0 - 1)
}

Most of Arab countries:

const week = {
    dow: 6,  // 1st day of week is Saturday
    doy: 12  // 1st week of the year is the one that contains the 1st of January (7 + 6 - 1)
 }

Now I understand

[jsdocker]

I would like to bump this. I would prefer an introduction to a semantically more meaningful setting variable and deprecating doy (as suggested here moment/moment#2115 (comment)), but even with the status quo, it should be better documented.

My suggestion would be to take Gregor Rayman's explanation as a basis (moment/moment#2115 (comment)). My proposal for the documentation:

Customizing Locale: 1st Day of Week & 1st Week of Year

To define the first day of week and the first week of year, customize the entry week:

week: {
    dow : 6, // Define on which day the week starts (0 - Sunday, 1 - Monday, ..., 6 - Saturday)
    doy : 12  // Define the first week of year 
}

doy is calculated as 7 + dow - janX, where janX is the x-th January that must belong to the week No. 1.

Three settings for the first day of week and the first week of year most used around the world:

ISO-8601: Europe

const week = {
    dow: 1,  // 1st day of week is Monday
    doy: 4  // 1st week of the year is the one that contains the first Thursday (7 + 1 - 4)
}

US, Canada:

const week = {
    dow: 0, // 1st day of week is Sunday
    doy: 6  // 1st week of the year is the one that contains the 1st of January (7 + 0 - 1)
}

Most of Arab countries:

const week = {
    dow: 6,  // 1st day of week is Saturday
    doy: 12  // 1st week of the year is the one that contains the 1st of January (7 + 6 - 1)
 }

ISO-8601: Europe -> doy: 4 // 1st week of the year is the one that contains the first Thursday, not the one that contains the 4th of January? I'm confused.

[warrenwhipple]

@jsdocker The week with the first Thursday and the week with the fourth of January are equivalent.
https://en.wikipedia.org/wiki/ISO_week_date#First_week

[jsdocker]

@jsdocker The week with the first Thursday and the week with the fourth of January are equivalent.
https://en.wikipedia.org/wiki/ISO_week_date#First_week

thank you very much.