WordPress.org

Making WordPress.org

Opened 14 months ago

Last modified 8 days 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
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 (2)

2847.diff (6.6 KB) - added by pbiron 14 months ago.
2847.2.diff (1.3 KB) - added by pbiron 8 days ago.
updated patch

Download all attachments as: .zip

Change History (11)

@pbiron
14 months ago

#1 @pbiron
14 months 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.


14 months ago

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


14 months ago

#4 @pbiron
14 months 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
13 months 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 13 months ago by keesiemeijer (previous) (diff)

#6 in reply to: ↑ 5 @pbiron
13 months 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 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.

Last edited 13 months ago by pbiron (previous) (diff)

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


2 weeks ago

#8 @pbiron
8 days ago

Related: #3699

@pbiron
8 days ago

updated patch

#9 @pbiron
8 days 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
Note: See TracTickets for help on using tickets.