Should we move the assets directory?

[tommcfarlin]

At this point, I'm interested in moving the assets directory above the root of the plugin directory.

This is the follow the new practices of the WordPress Theme repository (as @garyj) has pointed out not long ago.

The typical Subversion repository structure is:

• assets
• branches
• tags
• trunk

As far as I'm concerned, plugin-name is analagous to the trunk directory, so this means that assets should be moved up one level; however, this places the directory with the changelog and the README which doesn't make sense.

Instead, it feels almost like we should create a trunk directory of sorts, but I'm looking for some additional input on how to best handle this.

[joshlevinson]

I'm a fan of this. I used the boilerplate for my first public plugin, and I admit - I was confused by the location of the assets directory. It makes more sense to me for it to be above the directory of the plugins files.

However, I also see your point about how moving it to the root places it with the changelog and README.

Since not everyone uses branches and tags, but most (that's a guess) use at least assets and trunk, I vote for creating those two directories.

[tommcfarlin]

That makes sense.

I think I may hold off on doing that until the version after this one is released. A lot of new work has done into this particular release, and I don't want to rework everything to catch users off guard; however, I'll probably be kicking this to a 3.1.0 milestone.

[nathanielks]

See, I find putting js and css at the root level is weird... I use assets for all my static assets: js, css, img, etc. why not move them into assets and leave the folder structure the same?

[tommcfarlin]

This would end up with the following Subversion directory structure:

• assets
  • -- banner-772x250.png
  • -- screenshot-1.png
  • -- screenshot-2.png
• branches
• tags
  • -- 1.0.0
  • -- 1.0.1
• trunk
  • -- assets
    • -- js
    • -- css
    • -- img
  • plugin-name.php

Which may be okay, but I don't know if that's the most common convention. I've typically seen js, css, and img at the root level.

I'm not against eventually implementing this, but I'd also like the gather some feedback from others, as well.

[joshlevinson]

I think that structure looks great.

I've seen js, css, and img in the root directory equally as often in a subdirectory like media or assets. assets as we are discussing here pertains to the actual assets of the plugin for the WordPress plugin repository, not internal use of the plugin. The naming convention and use of an assets directory within the actual plugin is best left up to the author of the plugin, IMO.

[franz-josef-kaiser]

Per default most frameworks name that folder assets. Should imho be a standard.

[tommcfarlin]

I like the idea of standardizing a way to handle this; however, when I look at other open-source Automattic projects - like Underscores - they do not do this.

So we're left to make a decision on if we want to deviate from the way things like this are typically done, or stick what's with more generally practiced.

I'm on the fence about it so am all for continuing this discussion.

[grappler]

I would say for _s it does not make sense to have an assets folder as there is only a js folder that would go in there.

Allot of plugin do not use the assets folder normally they do have all three folders. WooCommerce, EDD and Crowedfunding are some that do use the assests folder.

I like to have as little file in the root as possible. I find it cleaner but it is only a personal feeling.

[franz-josef-kaiser]

The world turns. Even without Automattic. :) I honestly don't care how they do stuff, as they're no reference to me.

I thought about simply naming it like the package managers do, but npm uses node_modules, bower uses components (or something custom) and we're better not talking about pear. npm normally is used for client side stuff (node modules) and bower comes handy when you're working with front end stuff. Therefore you can target whatever folder you want. In short, there's no standardization in general from asset/dependency managers, but with most projects like Ghosts Caspar theme assets is what is used and what everybody understands - and it's shorter than dependencies.

What I'd suggest to avoid is divding stuff into css and js folders in there. Simply because there's no such thing any more. A lot of the current front end projects like Twitter Bootstrap, Foundation, etc. have both css and js files. While splitting them up is possible, I highly advice against it. Therefore I'd simply go with assets and leave anything in there up to the developer.

I got no opinion on img folder currently, but I'm not sure if it's a good idea to stuff that in there as well as the folder might get a lot of stuff added and deleted (automatically) during development.

[barryceelen]

I was browsing the codex to see what it uses in its examples, eg. for wp_enqueue_js, given that developers new to WordPress would look there first, but to no avail :)

Usually I prefer to have js, css and images folders in the plugin's root, probably because it feels most natural to me for them being on the same level as the languages folder. Plus it keeps me from opening yet another subfolder to reach the file I want to edit, all nice and tidy on top of the file list in my editor's sidebar.

[nathanielks]

I really like @franz-josef-kaiser's thought. Though, I don't really use a lot of those frameworks, so it doesn't affect me to much.

Something I'm hearing a ton is that everyone has their own way of doing things, which seems to be "the WordPress way." However, that doesn't necessarily make it the best way. Other projects like rails and such are far more opinionated than WP is and use widely accepted best practices. I think this is an opportunity to set a best practice for WP, or at the very least an opinionated best practice. Thoughts?

[tommcfarlin]

I'm a fan of opinionated development - it's one of the things that drew me to Rails years ago; however, I'm not sure I'm of the same opinion that assets need to exist within the core of the plugin directory.

At least not yet.

@franz-josef-kaiser's thought on Automattic is true, but @barryceelen brings up the point that a lot of new-ish developers are often going to use references that already exist - like Underscores, the Codex, and other plugins - many of which do not currently use an assets folder.

For the time being - at least for this version (which is shaping up to be 2.6.0), I'm going to leave css, js, and img in the root; however, I'm completely open to revisiting the discussion for 2.7.0 which while likely have some significant improvements over this version, as well.

[tommcfarlin]

For 3.0.0, the structure of the plugin has changed so that it mirrors the structure of the WordPress Plugin Repository.

All other assets (such as images, JavaScript, CSS, etc.) are contained within directories for their respective areas of the site (like the Dashboard, etc.).