Multiple Recommended Versions

[Katrix]

It would be neat if there was support for displaying the recommended version for more than one version of SpongeAPI (or minecraft in the case of mods).

I don't think it's that important for sponge plugins as the goal will be to minimize API breakage in the long run from what I understand. However for Forge mods, which can normally only be used on a few or one specific version of minecraft, it's a big hassle to have to try to find the recommended version for your minecraft version.

The way I see it is that for Sponge, it would group them by the api, while for Forge it would just group them after the minecraft version.

---

Edit by @phase: See the current proposal here.

[phase]

I'd like to make recommended versions per-channel instead of per-verision.

This will allow us to combine tags for projects to display on the front page. I've got an algorithm in mind to sort them.

[mbax]

Make sure to preserve disallowing recommended for a channel marked as non-reviewed.

[phase]

I would still like to hear input on this.

@dualspiral brought up the idea of having multiple jars per version. I think this will unnecessarily complicate things. Having one jar per version means we can separate versions from each other.

Let's say I have a plugin called PhaseHome, and I have Sponge API 7, 8, and BungeeCoord specific variants. Let's also say that the differences between API 7 and 8 are too great to be able to put in one jar, so we need these in separate jars. That's 3 jars per version.

Our current way to display this is as such:

Name	Channel	Tags
1.0.1-bungee	Bungee	BungeeCord
1.0.1-sponge8	Sponge8	Sponge: 8
1.0.1-sponge7	Sponge7	Sponge: 7
1.0.0-bungee	Bungee	BungeeCord
1.0.0-sponge8	Sponge8	Sponge: 8
1.0.0-sponge7	Sponge7	Sponge: 7

The channels here can be anything the user wants. We could put both the Sponge versions in one channel, but if I were making this plugin this is how I would do it.

I believe that flattening the versions instead of hiding version specific jars would help eliminate confusion. Users can even filter by channel to get download links to the exact things they want. Having multiple jars per version could muddy things up and cause confusion, but if we can figure out a system that works I'd be okay with that. If we were to redo versions, though, it would be a radical change to the core models of Ore. If we deem this is the best course of action for Ore, we can do it, but it would take quite a bit of rewriting.

I believe recommended versions per channel with an active / inactive state is a great alternative to everything that has been lacking. I posted this in the staff channel the other day (edited a little bit for context):

Active: [SpongeForge XX] [Forge XX]
Active: [Sponge 8]
Active: [Sponge 7]
Inactive: [Sponge 6]
Active: [Lantern XX]

So let's say a user has these channels. This would get condensed to
[SpongeForge XX] [Forge XX] [Sponge 7, 8] [Lantern XX]

This is obviously a crazy amount of tags to put on the front page. What's interesting about these tags is that Forge and Sponge are probably the most important, and they have the least "platform priority"

Platform Priority is what determines which platforms override others (SpongeForge overrides SpongeCommon overrides Sponge, Paper overrides Spigot overrides Bukkit (not implemented))

We can use this to filter out tags and only display the platforms in a platform category with the lowest priority.
Meaning this would cut off Lantern and SF as they are higher than Sponge
[Forge XX] [Sponge 7, 8]

This is most likely the best information we can give the user. We say it works on these platforms, and when they go to the versions page they get more specific platform options.
What's good about this method is that if a plugin only works on SpongeForge, we would only display SpongeForge as it wouldn't have a Sponge API tag to display, since it would need a version with it in a separate channel. But if it has a Sponge API channel and a SpongeForge channel, it'll display the Sponge API tag because that's the most generic platform it can go on.

I still believe that this is the best course of action. This will allow us to display the information the user wants on the front page. And, using the information we've collected from the tags, we can filter by Sponge API version (#294).

As this is a core part of Ore, I would like a lot of developer and community input as to what action we should take. I believe the system I have described (having recommended versions be per channel and optionally being active to be condensed onto the front page and other plugin lists) is simple to implement, provides users the best information up front, and will help users search for the plugins they want. and then after that we can implement machine learning

Again, I would love to hear input from anyone who reads this issue. I'm going to post it in the Discord channels to get some input.

[ryantheleach]

I think phases suggestion also makes more sense, as multiple jars per version makes reviews difficult; the workflow for the average user would be to update API 5 build, upload, update API 7 build, upload, which now means that versions need to be editable to add more jar's which would require way too much refactoring.

Especially considering the review status is tied largely to versions.

Elsewise they would be releasing multiple versions anyway, to fit their workflow, which means you would also need multiple RB per channel.

So it's far easier to do it per channel.

I'm not saying that multiple jar's shouldn't be looked at per version as a feature, but a single version should be a single release.

Cross SpongeAPI builds is usually (for most plugin developers), multiple releases.

Multiple jars per version should be for things like, a webserver component of a plugin, or a UI for perms editing, or an API provided by your plugin service, if you don't want it all in one jar.

Future work / pain points could be:

Splitting a channel, e.g. you have 1 main channel, and when the new API release is out, you want to move all the versions to a different (compatible rules, non-review etc) channel.

Assigning a channel an API version for display purposes?

Promotion of release candidates to releases via channels? idk.

[phase]

Assigning a channel an API version for display purposes?

I don't think doing platform-specific things like this will be good as other platforms aren't going to have a notion of an "API version".

when the new API release is out, you want to move all the versions to a different

Promotion of release candidates to releases via channels? idk.

Editing the channel a version is on is TODO #615

[Katrix]

I mostly agree on what Ryan has to say here. That said though if I had to choose between channels and multiple jars, I'd pick multiple jars exactly because cross SpongeAPI versions are always done as a single release for me, and having to treat them as multiple releases is kind of tedious.

Before I used the API to deploy, that was very tedious as I had to do the exact same steps 3-4 times in a row. Upload version, upload signature, disabled forum posts except for the last version, change the changelog to something I had in a notepad, make sure everything looked fine, and continue to the next one. Even with the API, I still need to make sure to go to each version and change the changelog to something which is the same for all the versions.

[dualspiral]

To be clear, I'm not against the idea of one recommended version per channel, that can co-exist with multiple jars per version.

My thought is specifically what Katrix said. At one point I was releasing three builds of Nucleus per version, each had the same set of release notes, meaning there were 3 posts on the forums, there versions on Ore of what is the same build targetting different APIs, etc. They are the same version on a functional level, with the same features, so why should they be separate in Ore? It's one release with three builds, not three releases. I would like to see Github Releases style release management, where I can have multiple jars that are all linked together on the same version.

I also see the flexibility proposed by different channels, because it allows you to recommend different builds for different API versions, and while both of these could exist, you could end up recommending an older build for a later API because of the multiple builds in a version. However, with filtering, if you have a list of recommended builds (or just releases) sorted in date order, this can also be averted.

Maybe that's a solution, remove the notion of a recommended build and use the Unstable monkier to mark something as non-release, and treat the latest versions of channels or API versions as our "recommended".

I do not think that multiple releases by version is as deficient as it has perhaps been made out to be, all ideas have their pros and cons.

I sympathise with the fact that this is a path of less resistance. I'm fully behind that viewpoint. I also want to ask about something @Ewoutvans has brought up, how this works with the "download" button on the home pages of plugins. With multiple RBs, how is this decided? Just download the latest RB? Take the user to a page with the RBs only so a user can decide which one to download? These UX elements need to be thought about too.

To talk about some of the points that have been made:

but if I were making this plugin this is how I would do it.

Sure, but remember that you're not the only user of the system, far from it. There will need to be some user education around channels to leverage this idea.

Users can even filter by channel to get download links to the exact things they want

Again, depends on how the project owner sets channels up. Filtering by platform and version will be more instructive for many projects, I don't think many plugin authors will care for channels. I would say that most will stick to one channel, which makes the version filtering more important than filtering by channels.

is simple to implement

Yes, simple to implement and I am fully behind that. We should always go for simple solutions as long as they meet the needs of the users. Also remember that we are either advanced users or developers of the system - it's sometimes difficult to see what the users want from this position and my viewpoint might be totally wrong for our average consumer, so I applaud this now being asked in the open.

provides users the best information up front, and will help users search for the plugins they want

I'm not sure that this is relavent to providing the best information up front though. Any system we use should be sufficiently decoupled from the grouped data - having multiple jars per version should also provide this information up front.

as multiple jars per version makes reviews difficult

It's either one version with multiple jars, or multiple versions with one jar each. Reviewers will still review the same amount regardless. I think it would suffice to say that one jar failing review in a version should affect the whole version.

the workflow for the average user would be to update API 5 build, upload, update API 7 build, upload, which now means that versions need to be editable to add more jar's which would require way too much refactoring.

Cross SpongeAPI builds is usually (for most plugin developers), multiple releases.

That's only because of the way it works now in Ore. How can we say it's anything else right now? I don't think it would be the case if we offer multiple file uploads for a version, with a warning that it's immutable afterwards, but I also don't have anything to back that up.

Where it would be tough is the use of the API, because you may want to upload multiple files at the same time using gradle (or whatever).

I'm not the average user, but I don't really see the evidence of this being the average workflow if this was implemented. Maybe it would be!

Multiple jars per version should be for things like, a webserver component of a plugin, or a UI for perms editing, or an API provided by your plugin service, if you don't want it all in one jar.

We're straying into non-plugin/mod files on Ore here, but I'd tend to disagree that it should only be for these things, multiple jars per version should be a logical grouping of like artefacts, which might be just different builds for different API versions.

[Ewoutvans]

Ore is "A Minecraft package repository" and we should not forget that.
A while back for a school project I recreated the idea of Ore as a C# project and some complains that people had been that we call an uploaded file a version. I think calling it a version is something inherently troubling in Ore now. Everybody is talking about 'jars' and ofc the Sponge community and its associates (Bungee, Velocity, Spigot, Forge) all use the java platform but we offer a Minecraft package repository. Why has it been decided that we only allow jars and not other resources (for example Spigot has a plugin Skript a people upload script to the resources section in Spigot).

If we move to the idea of having "files" we can make some additions like for instance bundling multiple files as recommended and making bundles downloads (a bit like you have on GitHub with the multiple downloads, we can if somebody makes a bundle set is as the recommended download that the button links to.)

This idea doesn't introduce much change for the reviewers because everything is still on a single download/upload based system and we just introduce a way of managing the Downloads tab in the UI. Having it as an additional feature leaves it to the author to make his workflow. Most small plugins won't need such complex system so if we just call it files nothing really changes for them.
The larges plugins that support more stuff can do bundling.

Switching to a files system gives us the opportunity to allow users to upload more kinds of content (Worlds, Resourcepacks, Scripts for plugins, Configurations...) that we during upload can detect because they don't have a mcmod.info (or equivalent) and we can just add them as platform.

With this idea we still keep the 1 recommended 'object' as an idea. The object can be a single file or a bundle. Doing it like this gives the advantage that if someone drops his support for channel SpongeAPi5 and forgets unmarks it that the homepage doesn't contain outdated stale information.

Recap and some ideas:

• Rename versions to files
• Allow bundling of files to a bundle
• Set recommended as a file or bundle (only 1 recommended object allowed)
• If recommended is bundle do condensed tags as @phase is suggesting
• Keep channels and the idea of unstable.
• If bundle contains 1 unstable file don't show tag in condensed
• Download as bundle or download single file in bundle.
• If all bundled versions are reviewed don't prompt unsafe download, otherwise do.
• keep behavior for single file downloads in bundle

[ryantheleach]

as multiple jars per version makes reviews difficult

To re-iterate what I meant by this comment;

Versions can not be editable once they were up, The usecase I described in my post was regarding how I expect that people who 1. arn't using the API, 2. arn't familiar with multi-output builds would complete the process. It was a bit of an assumption.

It's that point that I was considering, making versions editable, that would make maintenance and reviewing an issue.

Without which, I would assume/guess that only 20% of the people making multiple builds for multiple API's would be consistent enough to create releases on both simultaneously, as opposed to backporting specific hot fixes on request / building them separately chronologically.

That's why I was leaning towards multiple channels over multiple jars per version.

With the right meta-data we could do and adapt to either, but it creates a higher maintenance burden, and gives developers & admins more then one way to do things, potentially complicating the UX.

[phase]

as multiple jars per version makes reviews difficult

It's either one version with multiple jars, or multiple versions with one jar each

Well, we could do both.

Something I discovered when replacing the metadata ripper is that Ore currently supports uploading ZIP files. I could adjust the system to allow these ZIP files to contain any number of jars, and rip the metadata out of all the jars present. This wouldn't take much code to do.

So think we should keep the "version" title, but allow one jar or a zip with multiple jars. We would also go through with changing to recommended versions per channel. I think this would be the cleanest approach with the least code changes that would satisfy everyone.

[mbax]

One zip of multiple versions would just make things harder for the user, who now has 3 plugins and 2 of them are for the wrong version.

[phase]

Yeah that would kill usage. What if we allow the zip to be uploaded but display the contents of the zip in a list and the user can download whatever files they want from it? If it contains different builds then the user can pick which one they want.

Though I still think that would clutter things up and that putting them in separate channels would be simpler. Maybe we should make a system that allows uploading multiple jars for different versions that land in different channels?

[dualspiral]

You're overthinking this now - you're thinking as a developer and not as an end user.

The simple question to ask of everyone is this. Take all preconceptions about how Ore works now out of your mind. If you were a new user to Ore with a new plugin, that you support multiple API versions with, and you release version 1.0 with API 5.1, 6 and 7 builds, as a user, what workflow do you expect (or would like to see)?

Similarly, if you are a user looking to download a plugin for API 7 where a developer has an API 5.1, 6 and 7 jar for the latest version, what you would expect to see?

Find out what the preferred workflow of the community is, and run with that. We're just pulling rabbits out of the hat right now. I know what I'd want to see, but I would rather know what others think, so I won't reiterate my standpoint here.

[ryantheleach]

what workflow do you expect (or would like to see)?

I would

1. Make the project first.
2. Upload some stuff.

In detail, I would want a way of marking each of my uploads as working with a specific version of Sponge API.

When I issue a hot fix for API 5, I would then reupload API 5 again only. Why spend effort reuploading API 7 if it works correctly?

If the API 5 version continues to work on API6 I would like a way to mark that as the version people should be using for API6, without reissuing an upload, or changing my dependencies.

Granted it is a different workflow then you would use, dual. but my previous projects arn't set up to cross-build.

Similarly, if you are a user looking to download a plugin for API 7 where a developer has an API 5.1, 6 and 7 jar for the latest version, what you would expect to see?

Preferably when I'm searching, I would like to be able to choose what API/implementation I am using.

Then Ore would show me what I care about.

Occasionally I may be curious about what plugins are/were available on all versions, so that I can request to see if it still works on latest, or think about upgrading my server if multiple plugins that I have are marked as updated.

Even more Ideally, projects I Star, would show me their status and whether they are "ready" for a given API version so I know if I'm safe to upgrade yet, or if I need to update any plugins that I have bookmarked.

[Ewoutvans]

The workflow described by @ryantheleach is a nice way for users and makes sense.
I would however like to make some suggestions to that workflow.

If developers do frequent releases and upkeep multiple api versions the current version page will get crowded and that doesn't benefit anyone. If we do multiple recommended builds I would like something like this:

• Table above versions table with the recommended builds

I want the download button on the project page to link to a page that only contains this table. (only if there are multiple recommended builds)
Maybe something like this:

• Extra download page for the recommended builds

By making recommended builds so explicit the developer will make better decisions about what to mark as recommended.
This ofc gives the problem about what if the developer drops API5, he might still recommend the build but won't update so we might want a tag 'unsupported' for recommended builds so the end user knows that this is a recommended build but doesn't include support anymore.

On the homepage we could aggregate the tags that are recommended and not marked as 'unsupported'.

[phase]

Preferably when I'm searching, I would like to be able to choose what API/implementation I am using.

If they’re in different channels, you can filter the channels. Dead simple for users.

If you’re talking about the home page, I just added the platform filter, and a Sponge API filter (and this a Minecraft version filter) will come once we can decide on what the best approach for this issue is. I still think recommended versions per channel is the way to go.

you're thinking as a developer and not as an end user.

I think a flat list is the simplest approach for a user. They can check boxes for what API versions they want to see, and a download link is directly in front of them. It clearly tells the user what platform & versions the plugin is for. Having complex uploads of multi jar plugin versions complicates things. Does a plugin version realistically need multiple files aside from different compatibility jars? Config files can be a separate issue, but I think that the use case for a version having multiple files isn’t good for the end user. They want one jar they can click download on and shove in their server. An obvious use case against multi jar versions is, as Ryan described above, bug fix releases for specific platforms. It would become very confusing for users if one area didn’t have the file they were looking for but another area did.

How would we display multiple files to the user? It completely kills the “one click download” we want to present to users. We could list out the specific files on the version page, but that would kill the download button unless we bundled all of them. We could list the files on the versions list, but that would clutter things greatly and confuse users about what they need to download. Having v1.1-API7 or whatever makes it simple for the user to click the download for that version. Channel names and tags tell them about what and where the jar can be used, and having these be filterable would make it simple for users.

(I’m on mobile so it’s hard to format this nicely but I hope I got my point across)

[Katrix]

I see two big problems with only using channels. First of, they are non standard. Every plug-in can use different names and colors for different API versions. There would also need to be a way to opt out of a plug-in appearing in the recommended per channel section. I do not want to promote both a 7, and a 7.1 build.

The second and much bigger problem is that afaik, a plug-in can only belong in one channel. If I want to make one snapshot build channel, one alpha build channel, one beta release channel, and one release build channel, and then also support 4 API versions, that's already 16 channels. They essentially become a glorified tag system. Also, from what I remember, there is a limit to how many channels you can have, and I'm pretty sure I'm close to hitting it there.

I feel this comes down to what type of workflow a plug-in uses.

Me, and I assume Dual cross-build. No idea how it is for dual, but for me, the chance that I have to ever release a hotfix for only one version is tiny as probably 95% of the code in a plug-in is shared between all versions. The rest is mostly boilerplate.

Note that im fine with going with the channel approach for now, but we should be careful and make sure we don't stop ourself from doing multiple files per version at a later point.

Lastly just another point, if we're ever going to be a maven repo that people can depend on, then it needs to be possible to have multiple files per version to support sources and javadocs.

[dualspiral]

@ryantheleach That’s not really a workflow, “make project, upload stuff”. I know that you’re more for @phase’s idea, but the point I was making was that I want to know how you would upload multiple files. One at a time? All at the same time? Would you assign multiple releases? Add ability to group like “versions”? How would you solve @Katrix’s question about multiple releases at the same time?

The point of my post is to find out what users want to see, what would be ideal for them. However, I do accept the point about the channels and recommended versions, I said as such in a previous comment of mine.

@phase As I’ve said before, I see the pros and cons of each way. I know what you are championing and we’ve argued it to death. If you read what @Ewoutvans has posted, he’s thinking about the downloading side and is coming up with solutions, some of which do make me feel better about the idea, but I do think multi file “versions” should not be discounted. Maybe not in the form I envisage, if some sort of version grouping can be done, then that may well be a good way of making a logical grouping.

I fail to see why you can’t filter multi jar versions by API version. You can still scan all jars and intelligently download the filtered version when a download button is clicked. I don’t see it being a problem for the end user if it’s done properly - selecting the wrong channel can be just as confusing.

We’re ultimatley going to disagree on a lot of what is said and suggested. This is why I want to to see other user input.

Hence, my post was directed at others who want to help shape this workflow. I know what we think. I want to know what other opinions are out there.

Finally, don’t lose sight of what this issue is about, particularly about what @Katrix said, this is as much about ease of use by uploaders as well as downloaders.

[Ewoutvans]

Also just a quick note (that is probably offtopic).
What about notifications? If someone subscribes (stars) a project they get a notification for every release if people start doing CI builds, beta and release builds this will lead to a mess real quick. We might want to implement something to only notify users about new recommended builds. 🤷‍♂️

Edit: Also what about forum posts, I think we have a system atm to disable a forum post during upload but that might need some refining.

[Ewoutvans]

Proposed changes:

• Upload multiple versions at the same time.
  
  

• Ditch channels and replace with tags

• Allow multiple recommended
  

• Always show recommended table don't hide the ones that don't apply to filter just grey them out
  
  (also switch Version and Tags in column order)

• Add View older recommended builds button (We only allow 4-5 entries on homepage and only show those tags condensed on homepage)

• Download button links to a recommended
  

• Make 'Set recommended' a toggle button can have as many recommended builds as they want have soft limit in UI based on date of release.

  • In future we want maybe some kind of logic to show these so if you upload 2xAPI5 and 10xAPI7 that it shows latest of API5 and latest of API7

• Add option during upload (similar to forum post) to send notification.

  • In future we want users to change 'Only recommended', 'All'

[phase]

I think we’re definitely getting somewhere good now.

—-

@Ewoutvans

also switch Version and Tags in column order

mmm I don’t know if this is great. I think switching columns randomly will just be confusing to users.

Upload multiple versions at the same time.

That’s going to take a lot of frontend work 🤢, but I think most uploader will enjoy it. The upload system definitely needs to be looked at.

Add View older recommended builds button (We only allow 4-5 entries on homepage and only show those tags condensed on homepage)

Do we want to have recommended versions be “recommended” forever or require the user to remove previous ones to add new ones? I think keeping them recommended forever breaks the purpose of them. I can see it being useful for archival reasons, but other than that it might just confuse downloaders as to what is actually recommended.

@dualspiral

SpongeBleeding

Context

I think this is a good idea on paper, but this can just confuse users. We could add descriptions to channels, but I think we’re mostly in agreement that static tags and filters will do a better job.

(not sure who said this, still on mobile because Comcast sucks)

I'm against people uploading snapshot API release plugins on Stable

I think in the end we’re going to have to write a Sponge API version parser. Parsing 7.1.0-SNAPSHOT and setting any versions uploaded with snapshot dependencies as Unstable would be perfect. Plugin developers don’t want their plugins being marked as Unstable? Tell them not to use the bleeding API. I think that’s a perfect way to dissuade developers from using it. We’ll also need it to combine versions like 5.2, 6.1, & 7.1 into 5, 6, 7 for the home page. That can be done once these changes are in place.

[dualspiral]

We were having a good ol' discussion on Discord earlier to try to thrash out something to present, I think those of us there were pretty happy, we just needed to put heads together and thrash it out real time. @Ewoutvans post was the result of that. Things may need refining, but this discussion was good to really work out if there are better ways forward. Thanks for keeping this open, it's been a tough one!

That’s going to take a lot of frontend work nauseated_face, but I think most uploader will enjoy it. The upload system definitely needs to be looked at.

It was going to happen sooner or later! This would be a big boon to someone like me that would release multiple versions at the same time and might want a GUI process over an API process. It may be better to split that into its own issue.

I think keeping them recommended forever breaks the purpose of them. I can see it being useful for archival reasons, but other than that it might just confuse downloaders as to what is actually recommended.

Low priority, but I would perhaps mark them as "old". We had a bit of a chat about that, the simple way is to only count the last 4-5 as recommended for viewing purposes. It is a difficult one though.

SpongeBleeding... I think this is a good idea on paper, but this can just confuse users

Yep, I agree. Just wanted to add the context.

I'm against people uploading snapshot API release plugins on Stable

I think that requires a bit more thought for the wider project, as it depends on release frequency of Sponge and this becomes a policy thing. If the API versions become more frequent, or we need people to start testing our next greatest API version (e.g. 1.13), we should support that. I'm totally in agreement of flagging them somehow though.

(Corner cases: note that Nucleus builds against 7.1 snapshot at the moment, but is fully compatible with 7.0 because of the tricks I employ - though I'd say that's on me to sort out, I can fix the dependency fine. There are some "universal" jars too that have multiple API versions in one jar - I propose handling that in a separate issue.)

[Ewoutvans]

@phase
the switching of the columns was an idea by @ryantheleach so he might want to chip onto this but the thinking is

• people will go looking for a recommended version based on the system they use.
• people will go look for a version based on the version string (maybe someone recommended them to use X version)
  so it makes sense using this logic to switch it around in the recommended panel

[phase]

Low priority, but I would perhaps mark them as "old".

Is there a use case for keeping old recommended versions as “recommended” when they’re not recommended anymore? If we put a hard cap of say 6 recommended versions, there is no confusion as to what the plugin author actually recommends.

flagging them somehow though

“All versions depending on a snapshot API (which is inherently unstable) are marked with an Unstable tag” is a good rule.

people will go looking for a recommended version based on the system they use.

I believe that but I don’t think changing the UI in some parts and not others is clear. I think the name of the version should go in the front because it is direct identification of the row unlike “Sponge 7” which might be in multiple versions (maybe multiple recommended versions? An “unstable” API 7 version and a “stable” API 7 version would be one use case). The first question I see a user having with that Ui, and the first question I had, is “why are they switched?” If we switch it for one we should switch it for all, but having the version name first is a great identifier as to what you’re downloading (I’m thinking of Dockter’s 1.7.5-sf-features version on one of his mods that is different than the Forge versions or the SpongeForge compatible versions, but it (I think) has the same tags as the SpongeForge versions).

[ryantheleach]

Is there a use case for keeping old recommended versions as “recommended” when they’re not recommended anymore? If we put a hard cap of say 6 recommended versions, there is no confusion as to what the plugin author actually recommends.

I'm not super attached to it, but my thinking was that once something is marked as recommended, having it become un-recommended is awkward for historical reasons.

User looks for the previous version they used, and see it's not listed? Where did it go, checks older? I still don't see it?

Having recommended be near-permanent is useful information, for users, admins, and reviewers.

Of course there should be considerations for UI crowding.

This is the state I see versions/releases following, the non-connected states show separate uploads, ie. it's impossible to go from snapshot channel, to pre-release channel without remaking a release.

I'm not sure about pre-release to release, maybe we could somehow support promotion or early notification or something for that in the far future.

So, Release, moves to Recommended Build via a manual "Recommend" action.
Recommend moves to unsupported / old either automatically, (a new version is released, for that platform version and is promoted) or manually.

You can undo/resupport that, by bumping it back to recommended, and you can deprecate a recommended build, back to stable if there are issues.

Old is something that was previously recommended, that was never revoked, basically.

It gets hidden, but users can see it was previously a recommended build in the history list.

recommended builds that are instead deprecated should look different again, perhaps I need another state in the diagram?

I believe that but I don’t think changing the UI in some parts and not others is clear.

I agree as well, which is why recommended needs to look distinctively different, not just slightly different. We can possibly rework the UI there a little, but the basic idea / workflow of switching the columns I'm a big fan for.

If we switch it for one we should switch it for all,

Disagree, distinct UI has distinct purposes. But they need to be recognizably different. the user asking themselves "Why are they switched?" isn't in of itself a bad thing. It drives curiosity and thought, and they might solve the question for themselves / guide them.

What is bad however, is the user getting them confused.

"but having the version name first is a great identifier as to what you’re downloading" Agree!

It's also aesthetic. But UX trumps aesthetics IMO.

[phase]

having it become un-recommended is awkward for historical reasons

Server owners aren’t going to care about the history of recommended builds.

User looks for the previous version they used, and see it's not listed? Where did it go, checks older? I still don't see it?

“User looks for the recommended build they downloaded. Oh, it’s not there? It has been replaced with a new one? Better download that.”

I think that’s absolutely a good thing.

I think if we have builds that are no longer recommended in the recommended section, we’re going to get a lot of confusion. Users might be inclined to use an older version that the plugin author doesn’t support for whatever reason. History is great and all, and we can log recommended versions in the moderation log, but showing unrecommended builds in the recommended panel doesn’t help anyone. Having multiple states a version goes through complicated things.

Author uploads plugin -> normal version

Author thinks it’s ready to be recommended to users -> recommends version

Author uploads new version with new features/bug fixes -> unrecommends old version (because it is no longer recommended) and recommends new version

I don’t see a reason to put versions in this limbo state of “it was recommended like 5 months ago but it’s still in the recommended section, it’s just under old”.
I think plugin authors will be fine with a “you have too many recommended versions” error. We simply tell them to unrecommend some. When a returning user looks at the page and sees the version he downloaded has been replaced with a newer version, he is more inclined to download it.

[ryantheleach]

@phase I'm 99% sure the reason why you arn't agreeing with me is due to lack of decent mockups for how it will work on the users end, and that if I can show you my vision you will change your mind.

, but showing unrecommended builds in the recommended panel doesn’t help anyone

This isn't what I'm suggesting at all.

[dualspiral]

It is historical, and there is a good reason why you might want to use an old recommended version - if you don't want to use the new version because of some change you don't wish to have.

Say I release Nucleus 2.0 that removes a feature, say GeoIP, with no replacement*. I may not recommend (or actively support) 1.x any more, so I unmark the versions as "recommended". However, a server owner wants to use a 1.x version because they still want to use GeoIP, but they want to grab it from Ore. This isn't so much of a problem if you have a smaller plugin that just releases stable, newly recommended versions in a linear fashion, but with how I plan to use Ore by pushing snapshot builds straight from my CI, as well as hosting pre-release testing versions, there is the potential for the old releases being lost in the noise.

This would also have been helpful with my 1.1.x builds, which I don't support but are the last API 5.1/6 builds and so could have been in a historical list. I wouldn't want my 1.1.x builds showing as recommended, but I'd want them to be easy to find for those who still want to run these API/Minecraft versions.

---

• no hypothetical plan here reflects my actual thinking about Nucleus, this is for illustrative purposes only.

[phase]

Okay, what if we grey out "old recommended" version? We'd also need a way for the author to put the version in that state. If we have a limit to the amount of "completely recommended" versions, then we can prompt the user when they try to make a new recommended version saying "You have too many recommended versions! Version X.X.X will be greyed out!"

[dualspiral]

We absolutely should do something to set it apart, and I think Ryan had an idea on what we could do, but don't quote me on that.

Limiting the number of recommended versions is fine, as long as trying to upload a recommended version via the API isn't impacted - that is, some reasonable action is taken, say setting the oldest recommended version for that specific API version "old", or failing that, setting the oldest recommended build.

[phase]

So to recap what we've discussed:

• Ditch channels
• Allow the user to mark any version as a "recommended version"
  • These versions will have their tags condensed for the front page (will be discussed later)
• Have a static limit of "active" recommended versions
  • Recommended versions that are "inactive" will be hidden / greyed out by default. Maybe clicking an arrow or button will expand the recommended versions box.

Some questions that need thinking:

• Without channels, we no longer have a way to mark a stream of versions as "don't review these." I think this might be a good thing because it can be used to exploit the system. This means that CI builds will go into the review queue, but adding an option to mass mark versions as "we will never review these" might remedy this.

[progwml6]

The channels are a necessary construct to handle those independent streams of data, and to segregate new WIP feature setups, etc. so that someone can find a newer compatible build with what they are using

[phase]

WIP feature

The Unstable tag exists for that.

find a newer compatible build with what they are using

Tags in general fill this. Filters on tags in the Version List will help users find they want faster.

[phase]

Multiple Recommended Versions Proposal

This is my proposal encompassing the changes discussed in this issue.

---

Channels are arbitrary labels that authors put on versions to separate them from other versions. A lot of the time, these arbitrary labels end up not being useful to downloaders. My claim is that automated tags do a better job at communicating to the user what versions work on their setup.

The primary focus of the discussions in this issue and relating ones have been "how do we make it simple for the user to identify what versions work with their setup?" This includes things like what versions the author wants to recommend to the user, tags telling the user what APIs / platforms the version works with, etc.

I think we should remove channels and not allow custom tags. My reasoning behind this is that the author will not provide any useful information in a tag / channel name that is less than 3 words (and isn't already a tag). Examples like SpongeBleeding and Legacy do not communicate to the user what the version actually is. If an author really wants to have a custom name for that version, they can name the version accordingly.

Dockter does this beautifully in SGCraft. He has versions for Forge, SpongeForge, and SpongeForge with new features. He suffixes the version name with forge, SF, & SF-new-features, respectively. He is using channels here, but I believe that the name of the version and the documentation on the front page is enough to tell the user what each version does. The Features channel he has created does nothing to communicate to the user that this version "includes new addons such as ZPM, ZPM Interface Cart, GDO, Auto-Dialer etc." Only documentation can do that. The word Features next to the name of the build can communicate that it is different from other builds, but the name of the build itself also communicates that. Adding a single or a couple words next to the build with a custom color behind it can not communicate anything well enough to justify having it. Version names and tags tell the user exactly what they need to know. (I do need to ask him why his versions for SpongeForge aren't showing the SpongeForge tag. That is a metadata error.)

One of the main problems with channels that @Katrix mentioned above is they are non-standard. Every project has different channels with different names and different colors, and they all mean different things. This puts a burden on the downloader because they have to learn how every project sorts their builds. Allowing custom channel names/colors and custom tags will only cause confusion to users, and naming version builds appropriately will have the same affect without the added complexity. Custom tags are no different than custom channels, and allowing the user to create their own will complicate things. We can't filter them. We can't make them look the same across projects. Authors can't put anything meaningful in the amount of space we could give them. Adding a suffix to the name of the version gives the same exact result without the flashy colors.

---

We still need some way to communicate to users what versions are recommended versions. Instead of limiting projects to one recommended version, we should allow authors to mark an arbitrary number of versions as recommended. @Ewoutvans made a beautiful mock-up that displays what this could look like (scroll up to see it). These recommended versions will be placed in a box above the normal list of recommended versions.

Having multiple recommended versions is important because now we know what versions are important enough to get information from for the front page. If you have API6 & API7 builds that are recommended, we can take those tags, combine then, and put them on the front page so that they can be displayed & filtered. I discussed an algorithm for combining tags in this comment.

We can not, however, limit recommended versions to tags in any way. They need to be separate. In Dockter's SGCraft fork, he has three concurrent recommended versions, two of which will have the same tags. We do not want to limit him in what versions can be recommended. Recommended versions are not bound to tags.

For historical purposes, an author may want to keep their list of recommended versions. Instead of displaying every version that has ever been recommended, we should only display a set list of recommended versions, sorted by the time they were recommended. The rest of the recommended versions will be hidden until the downloader hits a button or dropdown that shows these older versions. A use case for this could be you have a bug in your most recent recommended version, and you want to tell a user to use your previous recommended version. That version needs to be archived somewhere so that a user can download it without digging through the entire version list.

---

These ideas together will help downloaders identify plugin versions that work with their setup in a more ergonomic way. Multiple recommended versions will allow us to better filter projects on the front page, and automated tags will help communicate to users what a version is compatible with. I believe these systems together do a better job of communication than arbitrary labels do.

[ryantheleach]

I agree with most of your points @phase , but have to disagree that using file / version names is superior to channels, and that channels confuse needlessly (They may confuse, but it's not needless).

For the same reason that types are important in strongly typed languages, vs using strings.

"He suffixes the version name with forge, SF, & SF-new-features"

Which now means that automated tooling can't tell the difference between them, without knowing their naming scheme.

Which means that the Ore UI/Database can't know the difference between them without knowing their naming scheme.

Having tags / channels for this sort of thing, allows automated tools, and Ore UI to provide superior UX. If channels or tags confuse, then the channels or tags are badly designed, or they were going to cause confusion as 'stringly typed suffixes anyway.

[phase]

using file / version names is superior to channels, and that channels confuse needlessly (They may confuse, but it's not needless).

I don't think they're better or worse, I believe they are mostly the same, except for channels having colors. It is not needless, but ineffective, and there are better ways of communicating information to the downloader.

More specifically, I don't see a use case for them other that separating / filtering builds. I believe a static set of tags can offer the same information and can communicate it in a clean & unified way.

Which means that the Ore UI/Database can't know the difference between them without knowing their naming scheme.

The database sure as hell doesn't need to know this. You might want this in the UI if you really want to separate builds, but filtering tags does the exact same thing. Currently, channels are arbitrary separators for projects. To create a unified UX, we need unified filters.

automated tooling can't tell the difference between them

This could be useful, but I believe the burden it puts on downloaders is too high for the benefits it may give.

[dualspiral]

On tags - I would be content with a hybrid approach. As there has been no comment on what the static set of tags are, I have three types I wish to propose:

• Stable - self-evident, I hope
• Pre-release (or beta) - some might like to promote builds for testing
• Snapshot - anything else

One of these probably should applied at all times. I have another tag that might be of use:

• Broken (to be applied retroactively if a serious flaw is found in a stable or pre-release build, pointing out to those who want old versions should NOT use that version)

However, custom tags would still be of use. They may have a "lite" and "full" version of their plugins, for example, but would exist under the same plugin ID. Tags like this would assist users in finding a specific set of builds at a glance. SG craft does something similar, I believe.

[phase]

(It has been a while)

They may have a "lite" and "full" version of their plugins, for example, but would exist under the same plugin ID

But would the uploader not name their versions accordingly?

If I want to release a new version of my plugin, v2.5, and I have two variants of my plugin, lite & full, I need to create two different version names for these versions so I can upload them to Ore. The version must be named with the variant of the version in mind or you can not clearly communicate to your downloader what the version is for. I would need to name my versions v2.5-lite and v2.5-full if I want to upload them both to Ore now. These name communicate what the contents of the version are.

One way we could change this is to have multiple jars per version, and have a "variant" associated with each jar. This would be an uploader-inputted field that will communicate to the downloader what category the version falls into. I would then upload both my v2.5 jars and say one is lite and the other is full.

I'm imagining a box that pops up with a table of any variants of a version when the user wants to download a version. If there is only one variant then the download button would just download the only variant. Felix & Ewout wrote rewrote some of the upload process in their Bootstrap 4 branch and we could adjust it a bit to allow uploading multiple files.

[Katrix]

So, been quite some time since the last update on this. Good news is, we're somewhat close to a good solution to this. Some things have changed in the time since the last update, and some things have not. Tags are still going to be there, and will likely not be customizable at least at first.

The part that is changing is the part about recommended versions. We have decided that the simplest solution to all our problems is to remove them, and compute what we "think" would have been the recommended versions instead. In general this will become a lot like CurseForge's different versions you used to see on the right when visiting a mod page (and still see on BukkitDev).

The way it will work is that we will look at the dependencies a version take, and from that determine roughly what minecraft version it targets. We will take at most 5 different platforms/platform versions ordered by tag stability (stable takes precedence over beta, which takes precedence over alpha) and release date. (Might also make another stability called promoted to get back most functionality from recommended versions).

Let's do an example

Version name	API version needed	Stability	Released at
1.0.0-4	4.1.0	Stable	2017-06-01
1.0.0-5	5.1.0	Stable	2017-06-01
1.0.0-6	6.0.0	Stable	2017-06-01
1.1.0-5	5.1.0	Stable	2017-07-01
1.1.0-6	6.0.0	Stable	2017-07-01
1.2.0-5	5.1.0	Stable	2017-08-01
1.2.0-6	6.0.0	Stable	2017-08-01
2.0.0-PRE1-6	6.0.0	Alpha	2018-04-01
2.0.0-PRE2-7	7.0.0	Alpha	2018-05-01
2.0.0-7	7.0.0	Stable	2018-06-01

What are the promoted versions here? They are 1.0.0-4, 1.2.0-5, 1.2.0-6 and 2.0.0-7. If 2.0.0-7 was not released yet, it would have been replaced by 2.0.0-PRE2-7

The system will be rolled out in two batches. First promoted versions, and then tags. We won't remove recommended versions until tags are out, but recommended versions won't be part of the V2 API, and as such, stuff that relies on them might not be completely stable in this period.