Skip to content
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.

Sign up for GitHub

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

Jump to bottom

State the date format explicitly #366

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

State the date format explicitly #366

wants to merge 1 commit into from
+2 −0

Conversation

sean-hut
Copy link

Problem

The ISO 8601 date format is ambiguous for 132 of the days of each year (about a third).

For example 2019-02-10 which is it YYYY-MM-DD or YYYY-DD-MM. The changelog does not say.

Proposed Solution

Explicitly state the date format.

Example

This commit is an example solution.

@jeffpaul
Copy link

@sean-hut I'm not aware of places where YYYY-DD-MM is utilized. Where have you seen that in use that would cause this potential confusion? Also, this seems like something for the Confusing Dates section and not where you're proposing this change.

@sean-hut
Copy link
Author

I'm not aware of places where YYYY-DD-MM is utilized. Where have you
seen that in use that would cause this potential confusion?

What I am suggesting is that there will be people out there that when
presented with a date like 2030-03-10 will not know if it is
YYYY-MM-DD or YYYY-DD-MM.

Situation:

  • a project is using the keep a changelog format
  • a user of that project is reading the changelog
  • the user is not knowledgeable in the variety of date formats
  • there are ambiguous dates in the changelog

Outcomes:

  • if there is no link to https://keepachangelog.com
    • they guess
  • if there is a link to https://keepachangelog.com
    • follow the link
      • guess after giving up before reading far enough down the page
      • find the date information after reading far enough down the page
    • don't follow the link
      • they guess

this seems like something for the Confusing Dates section and not
where you're proposing this change.

It is because of the situation and outcomes described above that I
suggested the date format be explicitly stated in the actual
changelog. This would removing the ambiguity of the date format.
It also eliminates the hunting for the date format described above.

@Nixinova
Copy link

there will be people out there that when
presented with a date like 2030-03-10 will not know if it is YYYY-MM-DD or YYYY-DD-MM

Are there? Really? I can't think of a single reason why you would use YYDDMM let alone assume an an unambiguous ISO date would be in that format.

@NicoHood
Copy link
Contributor

@Nixinova I agree with sean, as I am always confused. I've seen so many projects and changelogs. They do it all different (which is okay), but having this very short, but super helpful information is really great! I am wondering, why I wasnt using this before, thanks @sean-hut

@koppor
Copy link

koppor commented May 18, 2021

XKCD-1179

Explanation: https://www.explainxkcd.com/wiki/index.php/1179:_ISO_8601

@jeffpaul
Copy link

@olivierlacan sufficient to close this as invalid as ISO standard is clear the format is YYYY-MM-DD.

@koppor
Copy link

koppor commented May 18, 2021

I personally really like a hint to the date format. Nevertheless, I would refine the PR

My proposals would be:

  • Craft a new version 1.2.0 containing a hint to the date format in the "Frequently Asked Questions".
  • Put the note to Added for the Unreleased version in CHANGELOG.md.

phieri
phieri suggested changes May 10, 2023
View reviewed changes
CHANGELOG.md
@@ -5,6 +5,8 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

This changlog uses the [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) of (YYYY-MM-DD).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a typo: changlog instead of changelog.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sean-hut ^

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally learned more. The RFC 3339 defines a profile for ISO 8601.

I would propose:

This changelog uses the `full-date` format of [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6), which is `YYYY-MM-DD`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@koppor while your proposal would be technically more precise, I feel it's an overkill due to unnecessary complexity.

Just open your referenced link. Does one really need to know all these semantics to understand that a date (a "full date" that is) is represented as simple as YYYY-MM-DD?

ravage84
ravage84 reviewed Jun 2, 2023
View reviewed changes
CHANGELOG.md
@@ -5,6 +5,8 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

This changlog uses the [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) of (YYYY-MM-DD).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shorter version (no need to mention "the changelog" & highlight the format:

Suggested change
This changlog uses the [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) of (YYYY-MM-DD).
Dates use the [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) of `YYYY-MM-DD`.

ravage84
ravage84 suggested changes Jun 2, 2023
View reviewed changes
CHANGELOG.md
@@ -5,6 +5,8 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

This changlog uses the [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) of (YYYY-MM-DD).

## [Unreleased]

Copy link
Contributor

@ravage84 ravage84 Jun 2, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @koppor , it should get a change log entry.

Suggested change
### Added
- Mention use of [ISO 8601 date format](https://www.iso.org/iso-8601-date-and-time-format.html) (`YYYY-MM-DD`).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@koppor koppor koppor left review comments

@jeffpaul jeffpaul jeffpaul left review comments

@ravage84 ravage84 ravage84 requested changes

@phieri phieri phieri requested changes

Assignees
No one assigned
Labels
None yet
Projects
Keep a Changelog 2.0
Status: No status
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
7 participants
@sean-hut @jeffpaul @Nixinova @NicoHood @koppor @ravage84 @phieri