Design File-Format for Sketch Plugin Spec

[florianbuerger]

We should have something that encapsulates all information for a plugin and possible additional meta- or build related information. For the first iteration we could expand the JSON I used for awesome-sket.ch

{
  "plugins": [{
    "name": "Name for the plugin",
    "url": "The website",
    "author": {
      "name": "The authors name is displayed next to the plugin name",
      "url": "and links to this url"
    },
    "image": "an optional image path or empty string",
    "overview": "A short description",
    "description": "A longer description displayed below the first paragraph. You can use markdown syntax to add links, bold, headlines etc."
  }
}

The missing points I notice:

• authors should be an array to support multiple contributors
• version number (preferably using Semantic Versioning
• Some special build flags or scripts that have to executed on installation

CocoaPods used a single master repo on GitHub to store all Specs, maybe we can adopt this as well. The repo consist of all Specs, one folder per Spec that contains every Spec version, for example Plugin-Name/1.0.1/Plugin-Name.spec

[ramijames]

Would it be possible to add a "category" from a set list so that users can view only those types?

[timuric]

I would like to request a ignore parameter, that would allow excluding files like readme file etc.

@ramijames Maybe categories could work simply as tag filter, so it would not be necessary to specify it in the description.

[florianbuerger]

Of course. We are brainstorming here so everything is possible for now :wink:

:+1: for categories, tag should be reserved for git stuff.

[shahruz]

Looks like a great start! Couple things I've noticed that may need to be addressed:

• Plugin groups.
  • Many repos contain groups of plugins. If they are all related, I think this works, but there are a decent number of "My Sketch Plugins" which don't necessarily belong together when browsing. Not sure how to best handle this besides requesting each Spec be a bit specific.
• Sketch versions. There are a few plugins that are only Sketch 2 compatible, or are made redundant by Sketch 3. Should we ask the author to supply compatibility info?

[timuric]

@shahruz Having a description of the minimum supported version would be very useful

[florianbuerger]

@shahruz All the grouping repositories are absolute then, we use the central repository. We have to force the plugin authors to write Specs for every plugin. Sketch version compatibility is a good point. There should be some field for that. Can you enable the wiki on the repository? We should move the format draft over there.

[shahruz]

Yep, done!

[ramijames]

For "image" we're going to have to define a default size.

[florianbuerger]

@ramijames Why? I don’t see a reason where tiny or huge images are a problem.

Not sure if the image attribute is that useful at all. Thought we could use it to display some sort of preview when browsing plugins. What do you think?

[ramijames]

@florianbuerger The reason is that if you have a place for an image and a large community where they are inputting all sizes of images then you have a large variation both in image dimensions, but in image quality. If the end UI needs an image, say 400x300, and users input different images of sizes 1200x200, 600x300, 80x40, then we have a problem of both ratio and how to stretch the image to fit.

Having a pre-defined image size for preview makes all of this much more straightforward.

[timuric]

If the image is optional what would be displayed for plugins that don't have image?

[florianbuerger]

Maybe if there is no image, the text can span the whole row? Clicking the thumbnail will open the real size image in a popover thingy? (Hopefully with animated gif support)

[timuric]

@florianbuerger Such inconsistency would negatively affect the readability of the list, and will look chaotic. Maybe add pictures on the right side, so the left edge of the text would be aligned?

[timuric]

Or maybe there can be an image placeholder, with a default icon. I can create such, perhaps a single block of lego that symbolises extension? :)

[ramijames]

Yes, we would have to define a "Default" image so that scanability of the list is not impacted.

[florianbuerger]

I guess there are many plugins out there where an image isn’t necessary or doesn’t add much value to the plugins description. If the ration of plugins without an image is much higher we should skip the image and just show the description.

On the next iteration we can improve the UI to show a lot more information as @ramijames sketched in #13

[timuric]

@florianbuerger You are totally right. Unlike photoshop plugins, sketch plugins are mostly small, free and non-commercial projects. I think majority of plugins authors would not have time for icons/logos.

[ramijames]

In general I agree: there is no real need for an image at all.

[shahruz]

Yeah, I think no image is the way to go as well. I can't imagine any image being rendered at that size will make it easier to understand what the plugin does exactly.

[shahruz]

@florianbuerger What do you think the best way to proceed is? Should we fork http://github.com/sketchplugins/plugin-directory and restructure appropriately, and we can begin to ask developers to fill out more information?

[florianbuerger]

I guess so. I’ve add an alternative structure design for the repo. I am not sure yet if we really need all old versions (variant 1). Maybe we can just put every plugin into one big JSON file so plugin developers won’t have to properly version their code using tags.

What do you think?

[bomberstudios]

I said it before, and I'll say it again: we're open to pull requests in sketchplugins/plugin-directory. No need to fork it : )

[shahruz]

@florianbuerger Sounds good to me! @bomberstudios Sorry, that's what I meant, I wasn't very clear! I would definitely like to keep all this data in one repo (yours) instead of having numerous catalogs.

[bomberstudios]

@shahruz no problem : )

[ghosh]

I was just thinking about this. What do you guys think about the plugin author creating and keeping the json file in the plugin repo itself? It seems more natural to me instead of having to fill out the details in an external repo. Also that seems to be the way most package managers like bower, composer etc work.

[matiassingers]

@Ghosh I totally agree that the specs/definitions should be in the plugin repos themselves.

:+1:

[ricburton]

One of the things I've noticed about the plugin community is that lots of the repos tend to be collections of plugins that the creator finds particularly useful rather than a tightly-defined set that solve a particular problem. If you're searching for a Sublime or Atom package they usually have a tightly defined purpose and a problem that they're solving.

Asking people to break out their plugins into multiple repos might be too much but I wonder if there's a good way to catalogue or categorize different sets of plugins that serve different purposes.

Just a thought :)

Richard

On 2 June 2014 10:43, Indrashish Ghosh [email protected] wrote:

I was just thinking about this. What do you guys think about the plugin author creating and keeping the json file in the plugin repo itself? It seems more natural to me instead of having to fill out the details in an external repo. Also that seems to be the way most package managers like bower, composer etc work.

— Reply to this email directly or view it on GitHub https://github.com/shahruz/Sketch-Toolbox/issues/15#issuecomment-44818811 .

[ghosh]

@ricburton Agreed. The spec allows for multiple plugins to be defined in the json file. Have a look at https://github.com/shahruz/Sketch-Toolbox/wiki#central-spec-repo-variant-2

[Arkkimaagi]

What would the filename be? I mean, what's the holdup on deciding this? :)

I see no problem in adding this extra file to my plugin repo, I just had to guess a filename: https://github.com/Arkkimaagi/ArtboardZoom/blob/master/sketchtoolbox.json

[shahruz]

I like having something more generic than sketchtoolbox.json. The JSON file is probably useful in other contexts as well. Maybe just info.json or something along those lines?

Working on coding up a backend for all this. Should have some news soon!