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

[pbiron]

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.

[pbiron]

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.

[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.

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

[keesiemeijer]

@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.

Hope we can get some feedback on this.

[pbiron]

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 modified in a given version than 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.

[pbiron]

Related: #3699

[pbiron]

updated patch

[pbiron]

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
   • see #3699
3. defaults the change type dropdown to introduced
   • this hopefully will address the concerns in 2847#comment:6 and 3699#comment:1

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

[keesiemeijer]

@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]

correct updated patch

[pbiron]

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.

[pbiron]

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.

[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',
);

[pbiron]

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!

[tellyworth]

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