Plugins: Best Practice Guide needed about spongedocs

[ryantheleach]

In my mind this is more a problem about educating users.

Plugins that use implementation specific or otherwise break between versions should be clearly labelled as such on the plugin repository.

Bukkit just had a version string that indicated the version of minecraft that a specified plugin was designed for use, this causes many people in the comments to be requesting updates when none is needed.

If I were designing the site, I would have implementation specific plugins required to list the implementations they require, forge, nms, granite, glowstone, and have an indicator / color showing a warning if the version of minecraft doesn't match the latest sponge release.

This indicator should not show a problem for a plugin that uses sponge API only.

[sibomots]

My advice is to present advice and examples that use Sponge, name Sponge, and depend on Sponge alone.
Bringing into the mix Forge, Bukkit, etc.. complicates things a great deal.
Usually these good examples are structured as follows:
A problem common to Plugin developers: XYZ
A solution to the problem using the Sponge API
Known issues: We know of the issue P, D and Q that deal with this. <further reading -- links to Java web sites, etc..>
Omit comparison to Bukkit or any other Plugin engine.

[Lunaphied]

This also might due well to see/comment on this SpongePowered/SpongeAPI#364

[maxov]

This is the exact same as Bukkit. The Sponge API should work for 95% of use cases, plugins that don't work need a direct NMS dependency. Recommended practice is to never depend on NMS, ever.

[Lunaphied]

That's not realistic though, if such a subsystem is used, we can write it
in a way that there is a best practice. Avoid but don't limit for those 5%
just because they're not as common.

[Inscrutable]

This issue is balanced on a knife edge between saying "never do this", and effectively giving instructions how to do it. I think we need someplace to recommend that Devs Don't Do That, and suggest making a PR to the API instead, hence the suggested Practice Guide. IF we do provide any more detail, it should be pointing out things using NMS/Forge/XYZ can break. Perhaps also some system we can use to flag these dependencies for users.

[Inscrutable]

I refined my ideas of how to develop content for a "Best Practice" document or two. Basically it involves asking the right questions to provoke discussion. There would probably be more to "Best Practice" than just relating to NMS/Forge. Here is some food for thought.
https://docs.google.com/document/d/1YZcBhHCuxnUw3o1hEU_TU9vWgDMV9a6IvwGRB3OrQyw/edit?usp=sharing

[ryantheleach]

On the callbacks page (https://docs.spongepowered.org/en/plugin/basics/events.html) it seems like callbacks are essentially reserved for advanced usage.

I suggest that the use of callbacks should be the method used to act on an event in 90% of cases where an event causes gameplay changes that isn't a simple cancelling of the event.

There should also be some regard to when cancelling is appropriate vs removing the vanilla callback, especially in regards to logging plugins.

[Inscrutable]

The floor is yours - the page now has content, and is ripe for expansion. May I suggest further additions be submitted as PRs if possible.