Version heading format

[gilmrjc]

Currently the version heading is

1.1.1 - 01-01-1970

According to #59 the statistics about dates are:

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

Apart from this statistics, there is an issue about separators between dates #199.

Also related to heading format there are doubts about codenames #140.

Using all this info I propose to change the version header to:

1.1.1 - Codename (01-01-1970)

The format is SemVer (date), and if you use a codename for each release separe the codename from the version with a dash SemVer - codename (date)

This change makes a good example of #28, CHANGELOG can be changed and improved over time.

[davidak]

I also used version (date) in the past and think it's a lot more readable than the current format.

@olivierlacan what do you think about this suggestion?

[beatngu13]

As already mentioned in #140, I think code names are somewhat optional and they probably only appear in major releases. IMHO the changelog should focus on the version number:

${VERSION} - ${DATE} (${NAME})

I think this is a bit easier to read because then the columns are always aligned, especially if code names don't appear in every release.

Aligned:

2.0.0 - 2015-12-03 (Bar)

1.1.0 - 2015-11-04

1.0.0 - 2015-10-06 (Foo)

Not aligned:

2.0.0 - Bar (2015-12-03)

1.1.0 (2015-11-04)

1.0.0 - Foo (2015-10-06)

[dominiksalvet]

@beatngu13 You made a good point with the alignment. Still, there are some catches though. MD renderers generally have their text fonts proportional and also there are some items between individual version titles. Thus, the alignment difference might not be so visible. However, I must admit that your point about readability and optional code names is right in place. Nevertheless, I don't agree with your proposed format of the version naming.

I would suggest the following version naming format instead:

2.0.0 (2015-12-03) - Bar

1.1.0 (2015-11-04)

1.0.0 (2015-10-06) - Foo

I have several arguments for that format:

1. Parentheses are usually used as a form of additional information to preceding text. And so, in the @beatngu13 proposal, code names in parentheses might look like additional information to a date rather than a version. E.g., think of the code name like 'Tomorrow'... 😄 ... so that's why dates are in parentheses after versions.
2. It is also easier to distinguish between version and its release date while keeping their association. Having another hyphen between them might make us to spot something like this 2.0.0-2015-11-04 at first glance.
3. Versions and its release dates look more associated (and they actually are). Having one less character (including spaces) between them does the trick.
4. Code names look more like a separate item, not connected tightly to versions and dates (and they actually aren't as they are optional, it is a version meta information). That also makes it easier to spot that code name if present. Again, having one more character between version with date and code name does the trick.
5. Inspired by @beatngu13, columns of this format are aligned to make this format more consistent.

@beatngu13 What do you think about my proposal? Do you agree/disagree?

[beatngu13]

I tried to follow the existing format to not cause a breaking change, but I also like your suggestion. As long as the optional name is at the end and everything is aligned to some degree, I'm good. 👍

[dominiksalvet]

@beatngu13 Glad to hear that! :)
@gilmrjc @davidak What do you think about my proposal above?

[dominiksalvet]

Hey, anyone here? Here is an example that uses my proposed format (except for not using code names).

[gilmrjc]

I like it, and for me it reads better because I can focus on versions and dates independently.

@olivierlacan can you provide your opinion on this?

[muratgozel]

I'm using the following syntax:

## [X.Y.Z] - YYYY-MM-DD
Summary of changes.

### Added
- Something.
- Another thing.

### Changed
- Something.
- Another thing.

### Removed
- Something.
- Another thing.

Summary of changes have benefits both on the developer and customer side:

1. Developer recognizes the release easier.
2. It is useful when you send release content to customers over various channels such as email. The subject of the email contains both version and summary in my case. Therefore, customer also gets familiar with the release.