Code reference requires archive page to display by version

[siobhan]

Code reference users should be able to browse the code reference to view the docs by WordPress version.

This should follow the URL structure per #324:

developer.wordpress.org/reference/versions/
developer.wordpress.org/reference/version/version-number

We may want to surface this in some way on the code reference landing page so that people can browse/search through file names.

[nicole@…]

the parser will have to determine if anything is different?
and if so, create a new post?
and if so, will it copy over the custom fields from the previous version? and the examples?

and we'll need to know which posts are new so we can go in and ensure the custom field data and examples are still relevant

I'm very interested to know how this will be implemented.

[GaryJ]

What benefit is there for being able to show code reference from, say, WP 3.2?

[samuelsidler]

Replying to GaryJ:

What benefit is there for being able to show code reference from, say, WP 3.2?

Not much, but consider trunk vs 3.8, for example. It's a good way to show changes between versions, while they're still in process.

[GaryJ]

Is trunk going to be parsed nightly and added to DevHub? For whose benefit? Adding documentation to DevHub that's going to be cached by users and search engines, but then potentially be out of date the next day anyway seems odd. Those who are working with trunk code will know exactly where they can find out the latest documentation - in the trunk source itself.

With everyone being encouraged to always run the latest version of WP, and trunk users competent enough to know where to look anyway, I'm not sure what the benefit there is for having docs for anything other than the latest stable version.

[DrewAPicture]

Replying to GaryJ:

Is trunk going to be parsed nightly and added to DevHub? For whose benefit?
Adding documentation to DevHub that's going to be cached by users and search engines, but then potentially be out of date the next day anyway seems odd.

Are you under the impression that massive amounts of docs will be changing day-to-day? Because I don't see it. I can see doc updates happening periodically, yes, but not to the point where it would be causing a caching race condition as it were.

With everyone being encouraged to always run the latest version of WP, and trunk users competent enough to know where to look anyway, I'm not sure what the benefit there is for having docs for anything other than the latest stable version.

I don't see much benefit in parsing docs for anything older than the latest "stable" version, and really would rather we only parse WordPress as closely to "now" as possible, e.g. trunk.

We dearly need to move away from this idea that documentation should follow release cycles, and instead embrace incremental change. Without it, we're still stuck in the stale documentation rut we're in now.

Think of it this way: If we only parsed the latest "stable" version, outdated/incomplete/inaccurate docs updated today will not be "available" until the next version is released. That's crazy.

[GaryJ]

Replying to DrewAPicture:

Think of it this way: If we only parsed the latest "stable" version, outdated/incomplete/inaccurate docs updated today will not be "available" until the next version is released. That's crazy.

That's a fair point, but the converse is also true - if trunk introduces a new function, and it's documented, then it will appear on DevHub whenever the WP-Parser is next run, regardless of whether the next version is out or not.

To counter-argue my own point, I guess making the @since tag clearly visible would help mitigate some of the confusion, especially if anything with @since greater than stable comes with a clear notice that it's something from the future.

In that case, it makes total sense to be *only* be parsing trunk (not even stable).

[DrewAPicture]

Replying to GaryJ:

To counter-argue my own point, I guess making the @since tag clearly visible would help mitigate some of the confusion, especially if anything with @since greater than stable comes with a clear notice that it's something from the future.

I was always under the impression that we'd theoretically have a way of telling the Code Reference what the latest "stable" version is so that when a "future" @since is encountered then we can either hide that functionality/docs or otherwise mark it as a future improvement or similar.

[Rarst]

I am strongly against parsing trunk. Even minor cases of stuff "leaking" from test versions, but not actually making it into release have caused unwanted ripples and broken code around.

Exposing unstable code as official code reference is Very Bad Idea.

ALso to be clear this ticket is about browsing by version introduced originally. Versioning of reference is not on the table right now.

[siobhan]

I think this has become a little derailed. We're not planning to have a complete code reference for each WordPress version.

The developer.wordpress.org/reference/versions/ page will be a taxonomy archive page. We plan to show what has been added in each version.

So:

developer.wordpress.org/reference/versions/1_2/

would display everything added in version 1.2 etc

[siobhan]

It's now possible to see what has been included in each version: ​https://developer.wordpress.org/reference/since/3.1.0/