WordPress.org

Making WordPress.org

Opened 2 years ago

Last modified 5 months ago

#3069 reopened enhancement

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

Reported by: SergeyBiryukov Owned by:
Milestone: Q2 Priority: normal
Component: Plugin Directory Keywords:
Cc:

Description (last modified by 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.

Attachments (3)

3069.plugin-directory.PNG (44.4 KB) - added by SergeyBiryukov 2 years ago.
3069.wp-admin.PNG (29.4 KB) - added by SergeyBiryukov 2 years ago.
3069.akismet.PNG (59.1 KB) - added by SergeyBiryukov 2 years ago.

Download all attachments as: .zip

Change History (18)

This ticket was mentioned in Slack in #forums by sergey. View the logs.


2 years ago

#2 follow-up: @Otto42
2 years ago

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

#3 in reply to: ↑ 2 @SergeyBiryukov
2 years ago

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.

#4 @SergeyBiryukov
2 years ago

  • Description modified (diff)

#5 @SergeyBiryukov
2 years ago

  • Description modified (diff)

#6 follow-up: @Otto42
2 years ago

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.

#7 @Otto42
2 years ago

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.

Last edited 2 years ago by Otto42 (previous) (diff)

#8 in reply to: ↑ 6 @SergeyBiryukov
2 years ago

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.
Last edited 2 years ago by SergeyBiryukov (previous) (diff)

#9 @Otto42
2 years ago

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.

Last edited 2 years ago by Otto42 (previous) (diff)

This ticket was mentioned in Slack in #bbpress by sergey. View the logs.


2 years ago

#11 follow-up: @Otto42
2 years ago

  • Resolution set to invalid
  • Status changed from new to closed

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.

#12 in reply to: ↑ 11 @SergeyBiryukov
2 years ago

  • Resolution invalid deleted
  • Status changed from closed to reopened

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.

#13 @tellyworth
6 months ago

  • Milestone set to Q2

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

This ticket was mentioned in Slack in #forums by sergey. View the logs.


5 months ago

Note: See TracTickets for help on using tickets.