Date wrapping convetion

[skywinder]

Hi. I'm developing related project Github-Changelog-Generator.
And has a question - what will be guideline for date wrapping format.
For example: in that project format like tag - date

I try to research, how people usually print date and here is a some stats:

• 90% of repo (try too look most starred repo in github) prints if format tag (date)
• 5% prints in the same format, like yours tag - date
• 5% don't print date at all

Examples:

• https://github.com/h5bp/html5-boilerplate/blob/master/CHANGELOG.md
• https://github.com/angular/angular.js/blob/master/CHANGELOG.md
• https://github.com/docker/docker/blob/master/CHANGELOG.md
• https://github.com/square/picasso/blob/master/CHANGELOG.md
• https://github.com/GoogleCloudPlatform/kubernetes/blob/master/CHANGELOG.md

So, I would like to discuss, what should be guideline for changelog format and why?

[mockturtl]

proposal A.1

Relevant changes to the vandamme specification:

• strike English-style date formatting. All dates are ISO-8601, or Unreleased.
• strike level 1 header option. All release sections are h2.

---

• LEVEL 1 or 2 HEADER WITH VERSION MUST at least contain the version number
• {{version_number}} SHOULD follow the semver convention.
• {{version_number}} MUST contain at least a dot (ex: "1.2").
• {{release_date}} is optional but if present it MUST follow one of these formats:
  • the full english style format: "December 14th, 2014" (ordinal suffix is optional)
  • the ISO 8601 format: YYYY-MM-DD
  • the text Unreleased
• If the release date is present, it MUST follow the form {{version_number}} / {{release_date}}

[skywinder]

@mockturtl great summary! Thanks!

MUST contain at least a dot

What the reason for this point?

If the release date is present, it MUST follow the form {{version_number}} / {{release_date}}

Why this form? I don't see a lot change logs, the use this convention.

[mockturtl]

What the reason for this point?

Well: that's a good question. I will speculate it's because of the regex their parser happens to use (equivalently, an assumption of "semver-like" version strings).

It's my understanding golang, for example, prefers monotonic integer releases. So I don't immediately see a good reason to defend this clause; let's strike it.

proposal A.2

• LEVEL 1 or 2 HEADER WITH VERSION MUST at least contain the version number
• {{version_number}} SHOULD follow the semver convention.
• {{version_number}} MUST contain at least a dot (ex: "1.2").
• {{release_date}} is optional but if present it MUST follow one of these formats:
  • the full english style format: "December 14th, 2014" (ordinal suffix is optional)
  • the ISO 8601 format: YYYY-MM-DD
  • the text Unreleased
• If the release date is present, it MUST follow the form {{version_number}} / {{release_date}}

Why this form?

Only because there's an existing specification to discuss, and it's simple. Loosening the constraint to hyphens, whitespace, parens, italics, ... does not seem harmful, but I don't see an advantage.

(Personally, I prefer no dates -- they can be recovered from git, and I don't think they add value.)

[elyscape]

(Personally, I prefer no dates -- they can be recovered from git, and I don't think they add value.)

Not every project is open-source and, even then, not all users know how to use Git or have the time to learn. Putting the date in the change log, which is generally distributed with the binary release, allows users to find out when a release was made and see how out of date they are.

[mockturtl]

The counter-argument is that nontechnical users want "latest," and will not read a changelog. (I just opined on issue 44: the proper audience of this document is engineers. Contrast, release notes.)

But we're just discussing my personal preference; I should probably not have mentioned it in this context.

[pboling]

Agree that dates are critical information in a change log.

[skywinder]

@mockturtl 👍

Only because there's an existing specification to discuss, and it's simple. Loosening the constraint to hyphens, whitespace, parens, italics, ... does not seem harmful, but I don't see an advantage.

As I mention above - 90% use tag (date) format. Since there is no advantage one format from each others - probably it's better to go with majority?

I agree with @elyscape, @mockturtl:
Since change log created special to not go to git to fetch essential info - I also think the dates should be in change log. But not insist, that they must be there.

[pboling]

I also agree that the date should be a supported, albeit optional, part of a change log spec definition. When I said "critical" I meant that they are "critically useful" to what I use change logs for in my regular development work.

[mockturtl]

Since there is no advantage one format from each others - probably it's better to go with majority?

The guiding principle should be the simplest thing that could work. Favoring GitHub popularity could yield a mashup of, say, Google's style guides.

We're bikeshedding, now, but I think vandamme got it right: header.split('/') contains the version and date.

---

From your examples: notice h5bp contradicts this proposal re: English dates. Angular contradicts it re: h1 headers.

[mockturtl]

Picasso's date is italic, and tags include the string Version.

• As it stands, do you read the proposal as allowing italic (or otherwise marked up) dates?
• As it stands, the proposal allows extra text in the version string, e.g. Version. What use cases require this?

proposal B

• LEVEL 1 or 2 HEADER WITH VERSION MUST at least contain +only+ the version number

[axd1967]

Personally, I advocate the use of the format YYYY-MM-DD : version.

This produces a visually more easy way to process the headings as a human reader, as it is a fixed format string followed by a variably format string.