Since Edge will contain many different features, we'll have to make sure that we don't lose track of particular core enhancements and corresponding drupal.org issues. New features will likely be added in upcoming major versions (from which there might be many, it's perfectly possible to get to Edge 7.x-24.x within D7's release cycle), so we absolutely have to maintain a way to at least be able to grep through the module to find all contained features, even if it is for documentation purposes only.

I currently see the following requirements:

- A unique keyword/term is used to mark some code (once) as a "feature".

- A reference to the corresponding drupal.org issue, either as complete URL, or just in the form of "#123456".

- Ideally, close or near to the actual main feature code. While the global @file would be an alternative, there'd be no context, which I think is preferred to have.

Not sure what else.

Right now, I'm thinking of something along the lines of

/**
 * [...]
 *
 * @feature #123456 Support stylesheets-override in theme .info files.
 */

Thoughts?

CommentFileSizeAuthor
#3 edge-HEAD.issue_.3.patch1.18 KBsun
#2 edge-HEAD.issue_.2.patch575 bytessun

Comments

jacine’s picture

jacine
she/her
Location New York
commented

I LOVE this idea.

I don't like @feature. I think we should just call it what it is: @issue.

sun’s picture

sun
Primary language German
Location Karlsruhe
commented
Status: Active » Needs review
StatusFileSize
new edge-HEAD.issue_.2.patch575 bytes

Hm. So this is what it could look like.

Thoughts, as they cross my mind:

  1. Perhaps the individual @issue directives should rather be added directly to the theme override/replacement functions, instead of the "global" hook_theme_registry_alter(). It's possible that a single "thing" (Edge feature) might be related to multiple d.o issues (which is even the case for the current two theme functions already, as the patches for those two issues actually cumulated various other issues into a single one).
  2. But then again, listing them in hook_theme_registry_alter() makes a nice overview/list, even when it may not be totally exact (though you can read the referenced issue and figure out which other issues are covered, too). OTOH, this bullet ignores that we might change the implementation once again in the future, which would require us to link to an additional, new, separate d.o issue. So this bullet is probably moot. ;)
  3. Not very happy about the syntax and coding style.
    @issue #123456 The title/description.

    ...is basically invalid in every possible aspect. ;) Though it's of course similar to the syntax of:

    @todo The title/description.

    However, we seem to have a proper separation between Doxygen "title/argument" and "description" here, so by all means, this would be more correct:

    @issue http://drupal.org/node/123456
  The title/description.
sun’s picture

sun
Primary language German
Location Karlsruhe
commented
StatusFileSize
new edge-HEAD.issue_.3.patch1.18 KB

Still not happy with it, but this looks and feels like a step in the right direction.

jacine’s picture

jacine
she/her
Location New York
commented
Status: Needs review » Reviewed & tested by the community

It's fine. If we need to tweak it along the way, we can. ;)

sun’s picture

sun
Primary language German
Location Karlsruhe
commented
Status: Reviewed & tested by the community » Needs work

#575298: Provide non-PHP way to reliably override CSS needs to be added now.