WordPress.org

Making WordPress.org

Opened 2 years ago

Last modified 5 months ago

#2847 new enhancement

allow filtering of @since tax archive by the type of change

Reported by: pbiron Owned by:
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch dev-feedback needs-refresh 2nd-opinion
Cc:

Description

It would be very helpful to allow filtering of the @since tax archive by whether the change in a given version was a "newly introduced" vs. a "modification" from previous versions.

This would be useful not only for developers but also for those writing dev-notes (or the Field Guide) as a new release is being readied.

Attachments (3)

2847.diff (6.6 KB) - added by pbiron 2 years ago.
2847.2.diff (1.3 KB) - added by pbiron 15 months ago.
updated patch
2847.3.diff (7.3 KB) - added by pbiron 15 months ago.
correct updated patch

Download all attachments as: .zip

Change History (19)

@pbiron
2 years ago

#1 @pbiron
2 years ago

  • Keywords has-patch dev-feedback added

The patch I just added implements the "type of change" filtering.

I'm more than open to suggestions for changes to the implementation if people think the general idea is a good one.

Of particular note is the fact that I do the filtering in a function hooked to posts_pre_query. This seemed the easiest way to do it at this stage. What would be easier though would be if phpdoc-parser were to add a specific post_meta that indicated whether a @since was an "introduction" or a "modification" and then the filtering would be done with a simple meta_query.

This ticket was mentioned in Slack in #docs by pbiron. View the logs.


2 years ago

This ticket was mentioned in Slack in #core by pbiron. View the logs.


2 years ago

#4 follow-up: @pbiron
2 years ago

I put together a little plugin that lets you run this via WP_CLI. I hope that the WP_CLI version will be helpful for those prepping dev-notes, etc for future releases. If the general idea of this ticket is accepted, it would be best to fold the plugin directly into wporg-developer...but I felt it best to do it as a separate plugin at this stage.

Anyone interested can get it from https://github.com/pbiron/wp-since.

#5 follow-up: @keesiemeijer
2 years ago

@pbiron Nice patch and plugin!

It feels odd (to me) that modified functions/hooks/etc are included in the since archives in the first place.
Another route could be to exclude them by default and add a checkbox to include them back.

I hope we can get some feedback on this.

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

#6 in reply to: ↑ 5 @pbiron
2 years ago

Replying to keesiemeijer:

@pbiron Nice patch and plugin!

thanx

It feels odd (to me) that modified functions/hooks/etc are included in the since archives in the first place.
Another route could be to exclude them by default and add a checkbox to include them back.

obviously, I can only speak for myself, but as a developer I am generally more interested in learning what has changed in a given version that what has been introduced, since those changes might adversely affect existing code I have written.

Hence, my reason for requesting that such changes be more easily discoverable in the @since archives.

Version 1, edited 2 years ago by pbiron (previous) (next) (diff)

This ticket was mentioned in Slack in #meta by pbiron. View the logs.


16 months ago

#8 @pbiron
15 months ago

Related: #3699

@pbiron
15 months ago

updated patch

#9 @pbiron
15 months ago

2847.2.diff addresses the following:

  1. does the change lookup via term_meta attached to each term in @since (see below)
    • I ended up taking a slightly different approach than I thought when I wrote 2847#comment:1
    • but it's still much more efficient than the original patch
  2. adds a deprecated change type to the dropdown
  3. defaults the change type dropdown to introduced

I have also released a new version of WP Since CLI mentioned in 2847#comment:4. This new version contains callbacks hooked to a couple of actions from phpdoc-parser to add the necessary term_meta to support 2847.2.diff:

  • if you've already slurped the sources with wp parser create, then the first time you run wp since the term_meta's will be added to the db before it's output is produced
  • if you haven't yet slurped the sources, then just activate the wp-since plugin and when you run wp parser create the term_meta's will be added
  • ultimately, the code in the wp-since plugin that adds the term_meta should be incorporated into phpdoc-parser. But I didn't feel it was quite ready for a PR against phpdoc-parser, so I did it this way

#10 follow-up: @keesiemeijer
15 months ago

  • Keywords needs-refresh added

@pbiron Is patch 2847.2.diff correct? I get patch does not apply while the first one does apply.

With the first patch I get a PHP warning: Warning: Parameter 2 to DevHub\since_change_type_filter() expected to be a reference, value given.

You don't need to pass the query by reference in the posts_pre_query callback function (since_change_type_filter)

@pbiron
15 months ago

correct updated patch

#11 in reply to: ↑ 10 @pbiron
15 months ago

Replying to keesiemeijer:

@pbiron Is patch 2847.2.diff correct? I get patch does not apply while the first one does apply.

No, clearly it wasn't :-) Not sure where I got that one.

2847.3.diff is what I had meant to attach.

#12 in reply to: ↑ 4 @pbiron
15 months ago

Replying to pbiron:

I put together a little plugin that lets you run this via WP_CLI. I hope that the WP_CLI version will be helpful for those prepping dev-notes, etc for future releases. If the general idea of this ticket is accepted, it would be best to fold the plugin directly into wporg-developer...but I felt it best to do it as a separate plugin at this stage.

FYI: I included output from https://github.com/pbiron/wp-since in a Change Log section in the post announcing the 4.9.8 Release Candidate 1.

This ticket was mentioned in Slack in #meta-devhub by drew. View the logs.


12 months ago

#14 follow-up: @keesiemeijer
12 months ago

This ticket was discussed in slack.
https://wordpress.slack.com/archives/C02RRH4GA/p1540836537085900

The introduced, modified and deprecated metas should be added to posts by the phpdoc-parser. The deprecated version should also be added to the posts wp-parser-since terms. This allows the deprecated posts to be displayed in the since archives. See #3699.

My proposal was to use post meta instead of term meta. With post meta you can do queries like this.

$args = array(
	'post_type'  => 'wp-parser-function',
	'meta_key'   => 'deprecated'
	'meta_value' => '4.9.0',
);

#15 in reply to: ↑ 14 @pbiron
12 months ago

Replying to keesiemeijer:

This ticket was discussed in slack.
https://wordpress.slack.com/archives/C02RRH4GA/p1540836537085900

The introduced, modified and deprecated metas should be added to posts by the phpdoc-parser. The deprecated version should also be added to the posts wp-parser-since terms. This allows the deprecated posts to be displayed in the since archives. See #3699.

My proposal was to use post meta instead of term meta. With post meta you can do queries like this.

$args = array(
	'post_type'  => 'wp-parser-function',
	'meta_key'   => 'deprecated'
	'meta_value' => '4.9.0',
);

I don't remember right now why I did it with term metas instead of post metas...but there was a reason I found post metas "harder :-)

That said, I'm not wedded to any particular implementation as long as the front-end functionality is there!

#16 @tellyworth
5 months ago

  • Keywords 2nd-opinion added

What's needed to move this forward? Can (should) the patch be adapted to use postmeta?

Note: See TracTickets for help on using tickets.