Automate @since tags generation using the `n.e.x.t` placeholders

[eugene-manuilov]

Currently, we use 1.0.0 for @since tags in the codebase. This is fine for now since we haven't released an actual version yet. Later on it may not work because some already implemented tickets might be postponed and included into later releases which means that we will need amend @since tags manually to match the release number.

What we can do is to start using @since n.e.x.t tags for new functions, methods, filters and actions instead of entering the exact release number. Then we can implement an npm script that will replace n.e.x.t with the correct version.

[felixarntz]

I'm in favor of adopting this approach, since it also allows for flexibility on what the next release version will be. By using n.e.x.t, we can easily do a search-replace as part of release preparation to inject the actual version. I agree a simple npm script would be helpful, and we'll need to document this - we will need to add release documentation anyway, also around what this means for updating module header translation strings, changelog etc.

The way we go here may also depend on the overall branching strategy we'll use.

[mxbclang]

Please vote for this approach with a thumbs-up or thumbs-down emoji. Voting will close on 1 Feb 2022 at 6pm GMT.

Use @since n.e.x.t tags for new functions, methods, filters and actions.

[mxbclang]

Voting is now closed.

Based on 13 thumbs up votes and no thumbs down votes, we'll proceed with this behavior:

Use @since n.e.x.t tags for new functions, methods, filters and actions.

Removing Needs Decision. label and adding Needs Dev label.

[felixarntz]

While we could now technically open a PR to change all @since annotations to be n.e.x.t, I'm not sure that will be needed, given that we're only going to have this in 1.0.0 anyway, and that version we already know and use in the code.

Of course we'll first release beta versions of it, but I don't think we should use those beta suffixes in @since annotations - WordPress core for example doesn't do that either. So my vote would be to close this issue simply as "completed". Note that the release instructions in #138 already mention a step around the new decision here, so that should be good.

[eugene-manuilov]

So my vote would be to close this issue simply as "completed".

@felixarntz let's use this script to create an npm script that will replace @since n.e.x.t tags with the actual version. I can prepare a PR for it.

[felixarntz]

@eugene-manuilov +1. Would be great to also update the release documentation as part of that PR, to use the new script you're introducing (rather than manually search+replace).

[kirtangajjar]

@eugene-manuilov Since you're planning to work on this, can you please remove the "Needs Dev" label?

It will be helpful for others who are filtering issues on Github looking for things to work on :)

[felixarntz]

@kirtangajjar IMO it's okay to keep the Needs Dev label on an issue until a PR has actually been started, or maybe even completed. It's still possible to filter to only find issues that nobody is working on yet, by filtering only issues that have no assignee: https://github.com/WordPress/performance/issues?q=is%3Aopen+is%3Aissue+label%3A%22Needs+Dev%22+no%3Aassignee