WordPress.org

Make WordPress Core

Opened 4 years ago

Closed 3 years ago

#14921 closed defect (bug) (wontfix)

WP_Dependencies is tagged as external but is core package

Reported by: hakre Owned by:
Milestone: Priority: normal
Severity: normal Version: 3.0
Component: Inline Docs Keywords:
Focuses: Cc:

Description

While creating some runtime and static analyzer tools I ran over a problem rating files properly as core-files with the following files:

  1. wp-includes/class.wp-dependencies.php
  2. wp-includes/class.wp-scripts.php
  3. wp-includes/class.wp-styles.php
  4. wp-includes/functions.wp-scripts.php
  5. wp-includes/functions.wp-styles.php

Those files are tagged as being package "BackPress". I suggest to remove this external constraint. The foremost reason is this code has been contributed to and is developed in WordPress core, so it's not an external but a core file.

Core files are tagged as package "WordPress" in the project.

The current @package value mislabels them as being external files (BackPress backports WordPress and other projects' code into a library of it's own).

As new subpackage value I suggest "Dependencies". Additionally the @since tagging of those files / classes / functions can be improved.

Most of the code has been contributed in 7011.diff by mdawaffe.

The current tagging has been contributed in 7550.r8991.2.diff and committed in [9002] (Related: #7550).

Attachments (2)

14921.patch (6.9 KB) - added by hakre 4 years ago.
14921.2.patch (6.9 KB) - added by hakre 4 years ago.
@since concrete as in wordpress

Download all attachments as: .zip

Change History (9)

hakre4 years ago

hakre4 years ago

@since concrete as in wordpress

comment:1 hakre4 years ago

Related: #14920

comment:2 follow-up: nacin4 years ago

These were extracted out of WordPress core and are now considered external packages as part of the BackPress library. Despite the fact that we maintain it, I find @package fine here.

At most, I would suggest:

@since BackPress r74
@since WordPress 2.6.0

comment:3 in reply to: ↑ 2 hakre4 years ago

  • Component changed from General to Inline Docs

Replying to nacin:

These were extracted out of WordPress core and are now considered external packages as part of the BackPress library. Despite the fact that we maintain it, I find @package fine here.

I can not consider files with wordpress core code that are still maintained in wordpress (and not BackPress) as external packages. And I doubt that there is such a consideration. That would turn the principles of Upstream upside-down.

BackPress is very closely to WordPress core, but that does not mean that it normally re-labels wordpress package files in WordPress.

I'm even quite sure that this misalignment in these five files has been done in error. There are other files that are in BackPress library and in WordPress as well which do not @package this way. It are just those five files that are out of the row. For no special need btw.

At most, I would suggest:

@since BackPress r74
@since WordPress 2.6.0

This can create problems with PHPdocs. @since by design contains the version of @package (manual):

Use @since to document revisions, as in "This function has been a part of this package since version 2.0"

Next to that, it mixes responsibilities. The BackPress project itself needs to keep track for the various -Press (bbPress, GlotPress) sister projects. That's nothing we can and should do in the wordpress project.


Generally spoken: If it's an external, it should be treated as an external. If it's not it's not.

Considerations that make some files external by PHPDocs while factually being plain WordPress code is underminig PHPDocs and is reducing and even hindering its use.

comment:4 hakre4 years ago

Related: #14783

comment:5 hakre4 years ago

Related: #14953

comment:6 hakre3 years ago

The misconception of treating wordpress code that has been re-labeled as "BackPress" is becomming more popular. Those files must be something pretty special that they deserve so many exceptions.

Related: #15280

comment:7 westi3 years ago

  • Milestone Awaiting Review deleted
  • Resolution set to wontfix
  • Status changed from new to closed

These files are part of BackPress and are used by more that just WordPress.

Not plans to change the labeling of these.

Note: See TracTickets for help on using tickets.