search

DevinVinson / WordPress-Plugin-Boilerplate

[WordPress] A foundation for WordPress Plugin Development that aims to provide a clear and consistent guide for building your plugins.
http://wppb.io
7.67k stars 2.25k forks source link

Assets directory #45

Closed GaryJones closed 11 years ago

GaryJones commented 11 years ago

Would there be any benefit in creating an assets directory, and including within init three images - screenshot-1.png, banner-772x250.png and banner-1544x500.png? These images would be plain textual images that explained the purpose, or gave the size in the case of the screenshot file, as placeholders for when the plugin is to be uploaded to the .org repo.

Having the images already created at the right size saves someone having to look them up, introduces them and the assets folder for someone who don't know about them, and encourages screenshots to be placed into the assets folder so they aren't part of the downloaded plugin. If someone isn't planning on uploading to the .org repo, they can delete the assets folder in a couple of seconds.

tommcfarlin commented 11 years ago

This is another issue that I've not yet come to a conclusion about so I've held off on implementing it.

  1. If I include an assets directory, is it fair to assume that images, JavaScript, and CSS go into that directory? For some projects, I've seen this done, but in the WordPress world, assets is only used for for plugin banner image.
  2. If we include the assets directory and only include images to represent the banner, we'd need to require instructions that this directory actually sits outside of trunk in Subversion in and an assets directory which isn't even a directory created by default in Subversion repositories, let alone the WordPress repository.

Bottom line is that I think it's needed, but I'm also wondering if this will generate confusion especially for beginner developers.

Thoughts?

GaryJones commented 11 years ago

No, the assets directory is a special thing that the .org repo looks for. It has nothing to with the plugin itself, only the display of it on the repo. It contains the banner images, and screenshot files so these don't bump up the size of the plugin unnecessarily.

It's not the role of this boilerplate to be instructing on how the asset folder works. Link the readme to Otto's post that announces it, and that's it.

tommcfarlin commented 11 years ago

No, the assets directory is a special thing that the .org repo looks for. It has nothing to with the plugin itself, only the display of it on the repo. It contains the banner images, and screenshot files so these don't bump up the size of the plugin unnecessarily.

Oh, of course. I was unclear - I know what the assets directory is used for in the WordPress.org point, but if we add it then I want to make sure we're clear on how it's meant to be used.

That was all.

It's not the role of this boilerplate to be instructing on how the asset folder works. Link the readme to Otto's post that announces it, and that's it.

I can get behind this. I think it rounds out the Boilerplate nicely by properly providing everything that's needed to have a fully-developed plugin.

GaryJones commented 11 years ago

To reiterate, screenshots for the .org repo can also be stored within the assets directory, as per the screenshot description at http://wordpress.org/extend/plugins/about/readme.txt - as such, creating a screenshot-1.png / .jpg serves as a reminder that folks like to see screenshots, and where they are best placed.

grappler commented 11 years ago

As far as I understand the assetsdirectory is above the plugin directory.

Screenshot image files should ideally be put in the assets/ directory (which you'll likely need to create) in the root of your SVN checkout.

http://wordpress.org/extend/plugins/about/faq/ http://make.wordpress.org/plugins/2012/09/13/last-december-we-added-header-images-to-the/

tommcfarlin commented 11 years ago

The plugin header files belong in the assets directory, but the screenshots for the plugin belong in the root of the plugin's directory (which is actually trunk in Subversion or whatever the current tags directory is).

I left a note in the README file about where the assets directory needs to be moved.

grappler commented 11 years ago

Ok, great. Sorry I missed that.

GaryJones commented 11 years ago

but the screenshots for the plugin belong in the root of the plugin's directory

To quote from my linked source above:

This screen shot description corresponds to screenshot-1.(png|jpg|jpeg|gif). Note that the screenshot is taken from the /assets directory or the directory that contains the stable readme.txt (tags or trunk). Screenshots in the /assets directory take precedence. For example, /assets/screenshot-1.png would win over /tags/4.3/screenshot-1.png (or jpg, jpeg, gif).

So while screenshots in the root are backwards compatible, it's better to have them in assets, so they are not included in the plugin zip download, making it significantly smaller.

tommcfarlin commented 11 years ago

I've experimented with moving screenshot-n.png to the assets directory, but I've actually had users ask if they should have a copy of the screenshots that were displayed with the plugin as it they saw it as a form of documentation.

That's why I've tended to stick with the old way of doing it - saves me time.

GaryJones commented 11 years ago

Presumably, the screenshots are visible on the .org repo - they can see them there :-)

tommcfarlin commented 11 years ago

Definitely - I'm still just going by what I've experienced first hand with some users.

I'm going to keep the ticket closed for now and leave the screenshots in the root; however, if there's more demand for moving the screenshots to assets I'll re-open and resolve this issue.