[FR] Different descriptions & screenshots for major versions of plugins

[khalwat]

Description

With the advent of Craft 4, and dual versions of the plugin store, plugin developers need a way to have separate descriptions and screenshots for major versions of their plugins that correspond with major versions of Craft CMS.

Craft 3 will be around for some time, and as features are added to Craft 4 plugins that the developer may not backport to Craft 4, that means plugin developers can't accurately present the features of their plugins.

Different plugin versions are going to need different descriptions, images, etc. imo. Especially as they diverge more and more. Sites running Craft 3 are going to be around for some time I think.

This will reduce support, and reduce confusion for developers looking at plugins in the plugin store, and allow plugin developers to accurately represent and promote their plugins.

The situation only gets worse when we consider Craft 5 plugins, etc.

[lindseydiloreto]

Agreed. Assuming that plugin developers are continuously adding new features (and not back-porting all of them), it would make sense for each version of the plugin to have different descriptions.

It's not far-fetched that a C5 version of a plugin would have features that the C3 version doesn't.

[brandonkelly]

This has been requested privately once or twice as well.

There are a couple issues:

• Architecturally, we are not remotely set up for it. There’s no distinct plugin listing data for Craft 3 vs Craft 4, despite appearances. The Plugin Store APIs each just support being told a target Craft CMS version, and will return the appropriate available plugins, release notes, etc., based on the known plugin versions that are compatible with that Craft version. Which is why you’ll get Craft version-specific results in the in-app Plugin Store, for your exact currently-installed Craft version. plugins.craftcms.com is just a lot less granular—if you visit the “Craft 3” Plugin Store, behind the scenes it’s just telling the API to return plugins compatible with craftcms/cms: ^3.0; and ^4.0 for the “Craft 4” Plugin Store. So moving to storing unique sets of plugin screenshots and descriptions per major Craft version would be introducing a concept of major Craft versions that doesn’t currently exist.
• It’s hard enough to get plugin developers to upload screenshots and fill in descriptions as it is. Asking them to start doing it for each major version would probably result in less overall screenshots and descriptions, for the sake of a small handful of plugins that would actually take advantage of it.

When you think about it, allowing unique screenshots/descriptions per major Craft version isn’t even the right approach. Because plugins can have their own major versions independently of major Craft version. Maybe that’s less likely going forward with Craft’s new annual release cycle, but even then, you could see many plugins only getting significant improvements worthy of updated screenshots/description every 2–3 years; not necessarily every year. So going by major Craft version is probably the wrong level of granularity.

Instead, we’re thinking a better approach might be to start pulling in plugins’ README files, similar to Packagist/npm, which would get stored per plugin version. If a Plugin Store listing has their description filled in, we would show both the description and the readme (making it clear where the readme starts so it’s not awkward). Otherwise we’d just show the readme.

As for screenshots, we could come up with a syntax for defining a screenshot gallery right in the readme, that could be extracted out into our gallery view. Ideally something that doesn’t look horrible on GitHub. Something like:

<details id="screenshots">
  <summary>Screenshots</summary>
  <img ... >
  <img ... >
  <img ... >
</details>

[khalwat]

Yeah, if it wasn't linked to the Craft CMS version, but rather some kind of meta file in the plugins repo, that'd work well too.

I'm not wild about using the README.md tho, because I have very different things in my README.md files than I'd want for the plugin's description:

• README.md is on the plugin's repo, with installation instructions, a pointer to the docs, etc. There's meta information in there that I wouldn't want in the plugin store, and there's no marketing-based materials in there either.
• With a custom meta file, you could also then put whatever specific things were needed such as image links, etc. in a structured format, rather than trying to shoehorn it into the README.md

What if instead there was a .craft-plugin-store.yaml or whatever format you wanted, and then IF that file exists, then you use it. If not, things carry on as they are now.

Very similar to other meta files that may be in a repository like .gitattributes or .codecov.yml, and are intended as overrides/meta info?

[khalwat]

@lindseydiloreto had the idea of a PLUGIN-STORE.md file or the like, that if there, is used.

Initially I thought it wouldn't be great because markdown generally isn't wonderful for structured data like the screenshots meta, but then I remember you can have frontmatter in a markdown file:

https://raw.githubusercontent.com/nystudio107/craft-retour/develop/docs/docs/advanced.md

---
title: Advanced Usage
description: Advanced Usage documentation for the Retour plugin. The Retour plugin allows you to intelligently redirect legacy URLs, so that you don’t lose SEO value when rebuilding & restructuring a site
---
# Advanced Usage

## Console Command

So that might actually work out pretty well?

[lindseydiloreto]

I'm not wild about using the README.md tho, because I have very different things in my README.md files than I'd want for the plugin's description.

^ I'd agree with this. Most READMEs are tedious and boring, more technical than sales-y. I intentionally try to keep my READMEs short, and just point people to the real docs.

@brandonkelly To build on your initial idea... instead of grabbing the plugin's README.md, you could use the PLUGIN-STORE.md file. And if the PLUGIN-STORE.md file doesn't exist, it can just fallback to the README.md (as originally planned).

[engram-design]

Agreed on the readme option points made by @khalwat which was my first thought. We could make it work if that was the only option.

A custom meta file would be nice, but I suppose might be a breaking change.

@brandonkelly your points are totally correct about not having these tied to Craft major versions. It's more about different major versions of the plugin itself. It's just this usually happens at the same time as Craft versions, so the definition is probably getting messed up here. Of course, no plugin developer is forced to increment their major version as Craft does, but most of us are. Then again, it's not just major plugin versions, as even minor versions add new features.

Granted, Craft 3 versions of plugins are likely stagnant at this point (not getting any new features), and in 1-2 years time, they'll be so out of date compared to Craft 4/5/6, that it will be a bit strange to cater for version 1/2/3/4 of your plugin listing.

I don't really see a simple way of handling this, short of adding "For v3 of plugin - these features..." in the plugin description, which really isn't that bad. Screenshots can also be handled like this adding notes to the image itself.

Maintaining entirely different listings would be neat for sure, but I can't think of a single example for app stores, or package managers that do this (Packagist, NPM, Google Play, App Store).

I honestly think we just need to write better descriptions.

[brandonkelly]

I like the idea of a dedicated PLUGIN-STORE.md file + frontmatter for screenshots. And if that exists for the resolved plugin version, we can use that in place of the store’s screenshots/description.

(And at that point I would not do anything with README.md.)

[khalwat]

I think that'd be a great solution @brandonkelly -- there for people who need it, in a format that's easy to write and parse, and totally optional for people who don't need it.

If you ever wanted it to be, it could even be the project config of the plugin store world, in that other meta information could be in there too.

I personally would rather update things like the description, screenshots, short description, keywords, categories, etc. by just pushing up a revision to the file than having to log into id.craftcms.com and changed them there.