Plugin Directory: Add dates to Changelog section in readme.txt example

[SergeyBiryukov]

Raised by @bethannon1 in ​#forums:

bethannon1: Anyone know why we don't require plugin authors to show the dates of their updates on their changelog? That would be super-handy.... Some put it in, but most don't.
...
For instance, because Ninja Forms puts the release date of updates on their changelog, I can tell that the new client site that I'm working in has not been updated since before September 2016.

sergey: We could probably pull the dates from SVN, however changelogs are basically freeform text now, like the rest of readme.txt, so automatically displaying the dates there, while theoretically possible, seems like a non-trivial task.
We could educate plugin authors instead and make it a guideline in Plugin Developer Handbook :)
...
A good first step would be adding dates to Changelog section in ​readme.txt example.

bethannon1: I like the idea of adding dates to that example! Easy to do, and at least some devs would follow along with that expectation.

[Otto42]

What should the dates look like? What would be most useful?

[SergeyBiryukov]

Replying to Otto42:

What should the dates look like? What would be most useful?

Just random dates next to version numbers in a human-readable format.

Current content:

== Changelog ==

= 1.0 =
* A change since the previous version.
* Another change.

= 0.5 =
* List versions from most recent at top to oldest at bottom.

With the change proposed:

== Changelog ==

= 1.0 (04 August 2017) =
* A change since the previous version.
* Another change.

= 0.5 (01 August 2017) =
* List versions from most recent at top to oldest at bottom.

[Otto42]

That's not a good change. Those headers are parsed and read and used for various things. They need to be version numbers only, they cannot contain dates as well.

Try again, that's an invalid format.

[Otto42]

Again, need another format. The format of the headers is intended to be the same as the versions. Changing it would break things like the Changelogger plugin, for example:
​https://wordpress.org/plugins/changelogger/

Pick another format, one where the date is not in the version header field. The format of the readme.txt files is not arbitrary. It's not a choose-your-own-adventure. We expect it in a specific format so that it is machine-readable. Code exists to parse it in machine-readable ways. We will not change that format in incompatible ways without a good reason.

[SergeyBiryukov]

Replying to Otto42:

Those headers are parsed and read and used for various things. They need to be version numbers only, they cannot contain dates as well.

Plugin authors already include dates there without noticeable issues, see ​Ninja Forms for example. That changelog is correctly displayed in both Plugin Directory​ and WP admin​.

The only issue I see is that changelog headings are not pulled into GlotPress for translation​, so the dates should be in a universal format like YYYY-MM-DD instead of English text.

If some custom code depends on those headings being numbers only, seems like that code should be updated to avoid potential breakage.

The format of the headers is intended to be the same as the versions.

It should be mentioned in ​Plugin Developer FAQ and ​How Your Readme.txt Works then.

The format of the readme.txt files is not arbitrary. It's not a choose-your-own-adventure. We expect it in a specific format so that it is machine-readable. Code exists to parse it in machine-readable ways.

I wasn't aware of that, thanks for the clarification. At a glance, the Changelog section does appear to be a freeform markdown text, same as most of the other sections.

Pick another format, one where the date is not in the version header field.

No problem, we could add the date after the version headings, like Akismet does: 3069.akismet.PNG​.

== Changelog ==

= 1.0 =
*Release Date - 10 May 2017*

* A change since the previous version.
* Another change.

= 0.5 =
*Release Date - 02 May 2017*

* List versions from most recent at top to oldest at bottom.

[Otto42]

Yes, the headings for the Changelog section is intended to be version numbers only, the same as it is with the Upgrade Notice section. If a plugin is doing-it-wrong, then we cannot guarantee correct results. It may be correctly displayed in areas where that data is just being displayed, but it will not be correctly parsed by other code that tries to parse it and use that information.

Ninja Forms is doing-it-wrong.

[Otto42]

Marking as invalid. The proposed change is starting to be adopted and already breaking code. This is an *invalid* format in the readme.txt, and we will not change the example until somebody comes up with an actual proper standard that does not break existing code.

Versions in the headers MUST be left alone. If you want a standard that includes the date, then create one that does not break existing systems to do it.

[SergeyBiryukov]

Replying to Otto42:

The proposed change is starting to be adopted and already breaking code. This is an *invalid* format in the readme.txt, and we will not change the example until somebody comes up with an actual proper standard that does not break existing code.

The proposed change is at the end of comment:8, not the initial suggestion. That's what Akismet does, and there's nothing invalid in it.

[tellyworth]

Altering the format seems problematic, but automatically storing or querying data from SVN is worth exploring.

[SergeyBiryukov]

Previously: #819