-
-
Notifications
You must be signed in to change notification settings - Fork 163
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs: Improve format documentation #963
base: main
Are you sure you want to change the base?
Conversation
built with Refined Cloudflare Pages Action⚡ Cloudflare Pages Deployment
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #963 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 10 10
Lines 373 373
Branches 94 94
=========================================
Hits 373 373 ☔ View full report in Codecov by Sentry. |
Can you please modify the description of the PR to make it more self-explicative? Thanks a lot! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good 🚀
|
||
#### Dates and Times | ||
|
||
Dates and times are represented in [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). This is a subset of the date format also commonly known as [ISO8601 format](https://www.iso.org/iso-8601-date-and-time-format.html). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a subset of the date format also commonly known as ISO8601 format.
This is not true. Here's a really good comparison: https://ijmacd.github.io/rfc3339-iso8601/
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @gregsdennis ,
I have two different suggestions for this:
1:
Dates and times are represented in RFC 3339, section 5.6. While RFC 3339 is often considered a subset of the ISO 8601 format, there are important differences between the two. For a detailed comparison, refer to this resource: RFC 3339 vs. ISO 8601.
2:
Dates and times are represented in RFC 3339, section 5.6. While RFC 3339 is often seen as a simpler version of the ISO 8601 format, there are some differences. RFC 3339 focuses on a smaller set of date and time formats and has stricter rules. It doesn't include all the features of ISO 8601, like week dates or very long years. For a clear comparison, check this resource: RFC 3339 vs. ISO 8601.
What do you think?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is 3339 considered a simpler version of 8601? I never thought that. I always thought they were just different. I was actually surprised when I discovered how much they overlap.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
RFC 3339 is a simplified and restricted subset of ISO 8601.
They have some similarities like Both formats support the basic date-time structure using the format YYYY-MM-DDTHH:MM:SS
and some differences like ISO 8601 allows reduced precision in the time format (e.g, only specifying the hour: 14:30) and RFC 3339 requires the full HH:MM:SS
format.
ISO 8601 provides more options than RFC 3339.
So, what should be our conclusion for this? Do you prefer one out of the above two options or you have anything else to add?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
RFC 3339 is a simplified and restricted subset of ISO 8601.
I have a problem with the word "subset". It's not a subset. There are 3339 formats that 8601 doesn't accept. In the comparison, you can plainly see this. It's not a subset because the 3339 circle does not exist completely within the 8601 circle.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Now you have the opposite problem that "distinct" means there's no overlap. Just say they're separate specs. The RFC is by IETF, and the ISO is by, well, ISO. They're different because they are attempts to standardize dates by two different standardization bodies.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dates and times are represented in RFC 3339, section 5.6. RFC 3339 and ISO 8601 are standards from different standardization bodies. RFC 3339 is from the IETF and ISO 8601 from the ISO. They are separate date format specifications with overlapping features. RFC 3339 enforces stricter rules and supports certain formats that ISO 8601 does not, while omitting features like week dates and very long years, which are part of ISO 8601. To explore their similarities and differences, refer to: RFC 3339 vs. ISO 8601.
I have rephrased it as per your suggestion. I will add the link to IETF, ISO official site and RFC vs ISO.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we're getting lost in the weeds here. We should focus on RFC3339 and maybe casually remark that, while it overlaps somewhat with ISO8601, it is a different specification with a different set of formats.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why are we mentioning the ISO standard at all? It isn't actually relevant. There are innumerable other standards that it isn't defined by.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's really what I'm trying to get at.
I am adding @jagpreetrahi to the discussion as they have been working on this in other PR. Now all the conversation is here. |
What kind of change does this PR introduce?
Resolves the Docs error by relocating the Format section and also incorporating the suggested changes from the participants of PR #664
Issue Number:
Summary
I have implemented the changes that were discussed in PR #664. Additionally, I have also checked the grammatical errors. Sorry! I did not ask to assign it to me as it was pending for the last few months.
If you have any other suggestions, let me know.
Does this PR introduce a breaking change?
No