Add documentation for "Incompatible" mods about spongedocs

[ST-DDT]

We definitely need (plugin) user feedback to create such a page.
Otherwise we won't know which plugins are incompatible and how they could be fixed.
Any suggestions for the location of that page? Top level or inside Creating a server or ...?

We also have to evaluate which plugins we consider to be important enough to be listed and whether/how to group them into common error groups.

[simon816]

IMO the forums are a better place for this. We already have a common issues thread. A forum thread can be easily updated as new information comes in and there can be discussion about alternative solutions.

[ST-DDT]

When it's ones where there is no fix that Sponge can do, and the mod has not been fixing it

Who verifies that their new version X (they didn't tell us about), has still the same issue and stacktrace? Who verifies that a new major version of Sponge has the same incompatibility. Who checks that the incompatible mod has a release compatible with the minecraft version related to the SpongeAPI version the docs reference? And does the user look at that previous API version's doc pages?

Maybe we should add a page regarding mod incompatibilities that just refers to the forums so that if you search the docs for that info that you at least get a lead where to look next.

[ItsDoot]

Will also want to include some examples of errors that show up from these compatibility issues.

[gabizou]

Farseek 2.5 might be fixing the crash outright, but as with world generation, it still might be altering some of the pipeline not to how we'd be using it. Refer to commit delvr/Farseek@31f786b
where the modification to redirect the Event bus calls is removed, that should allow SpongeForge to load again.

I've not been able to verify the world gen pipeline in a while with far seek and sponge forge in play, but I can't imagine that the hacks/reflection workarounds to try and move the transformer ordering is going to work as of yet.

[Inscrutable]

We currently have no mod-specific warnings in the Sponge Documentation, by choice.
There are some concerns I have about the current proposal:

• Firstly, in principle we want to avoid recommending or disapproving of any third party mod.
• Second, If we were to have comments relating to mod-specific incompatibilities, the page will necessarily be quite volatile - mods (or SpongeForge) may update to fix problems, and work-around fixes may appear. The page has significant potential to bloat as new incompatibilities arise.
• Third, checking the accuracy of the problem, the solution(s), and finally documenting it is an additional workload. We'd also need to include the range of versions where each incompatibility arises, and probably retain it as a record for older versions.

If we do decide to create such a page, it might be a natural extension of the "debugging" page (which probably needs going over anyway). By the way, Mystcraft is another one for the list.

[LordRalex]

My view of it was that we should not be requiring users to essentially go to the Discord to get our "generic puke of text" which hasn't changed in some time for some issues. I would rather give users the ability to self-service, especially if we are adding code into Sponge to detect such issues.

I did not view it at all as recommending/disapproving of mods. It is simply a "To use X mod with Sponge, you may need to make some changes, due to compability issues". It is not a recommendation or a "don't use" list.

An example used to be foamfix, which was always disable a certain config entry. We basically got used to just going "if you see foamfix, do !?foamfix". And we as the "support" knew about it. I would prefer that our knowledge and common fixes be somewhere more public and discoverable for generic users so that they aren't required to join the Discord just to get told the fix.

Hammercore's fix for example is disabling a config entry. While we can have a trick for it, unless you know Hammercore does that, we easily spend time re-reading and re-thinking if it's not as common, or it's new. And this one is one that from how the dev of Hammercore put it, won't be fixed any more than how he did it. And I know finding that one line to change requires searching Discord (until we put a trick in).

I would say that only mods/plugins that are known to not be getting a fix and/or there is fundamental issues that we can't simply drop and run sponge should be in this list. One-offs don't have to be on this list. I would be fine with listing affected versions myself.

I would say if we see it commonly in the Discord, it's a candidate. This is why only the ones I listed (and MalisisCore was the M I was thinking of, which is the old mixin line) was the ones that came to mind. One-offs don't need to be listed, but if the Discord is commonly seeing them, we should try to make it a bit more obvious somewhere else too.

[Inscrutable]

Actually, I think mystcraft is completely incompatible, because it warps the vanilla worlds system. At some point we have to flat-out admit that some mods won't work with Sponge. Also for reference, MalisisCore is a common mod that has been causing old mixin problems.

So, if someone wants to try putting together a draft Incompatibility page, everyone else can pile on their notes and we can collate it. We'd want the version info for each mod, correlated with SF versions where possible, the problems it causes, solutions (where known, such as update to version XY), and perhaps a unique part of the related error log.

But the larger burden here may be in updating the page as the situation evolves.

[LordRalex]

To me, forums make sense for the short-lived ones (like, they are fixed within a few weeks).

When it's ones where there is no fix that Sponge can do, and the mod has not been fixing it, then I don't think them being on the forum makes sense. To me, the docs should have the information a user needs to get going. We shouldn't need to have users going to multiple places to work things out.

[dualspiral]

Who verifies that their new version X (they didn't tell us about), has still the same issue and stacktrace? Who verifies that a new major version of Sponge has the same incompatibility. Who checks that the incompatible mod has a release compatible with the minecraft version related to the SpongeAPI version the docs reference? And does the user look at that previous API version's doc pages?

Related to this, the assumption that users:

• will do this for us and come back to us and tell us without prompting; and
• will read an entire forum thread

are not good assumptions to make - as we've seen in the past many times in Discord, IRC, forums, etc. We can only work with the information we're given at hand. We should include version numbers of mods that we find issues with, to make it clear that's what we know and to tie the advice to. If a mod updates to fix this issue, the advice is still valid for a specific version and if the mod is in a modpack, that advice will still be relevant for some time.

A forum thread can be easily updated as new information comes in

So can the Docs, it's just a PR away, but I guess your concern would be that we'd need to be quick on our toes about it.

there can be discussion about alternative solutions.

I can see the value of discussion on the forum post and I do agree with you, but I fear that what will happen is that the same questions will get asked over and over on the thread. I would be in favour of this though, I'd rather be proven wrong than assume I'm right.

The reasons I was one of those who suggested the docs as a place for this are:

• Docs are, as Ralex suggested, the official documentation pages and I do think we need to encourage people to use them more.
• Docs are translatable - if people translate them they can support the wider user base more easily.
• There would be a more immutable URL that we could include in SpongeForge builds to point users to when things go wrong - I don't think the forums URLs will change but we have less control over what the forum software does.

Just my tuppence. I can see either forum based or docs based solution working, but at the very least, if we have a forum post with the incompatibilities on we should mention it on the docs.

[Inscrutable]

It seems a new docs page is inevitable, either as glorified pointer or source document.
Either way, whatever we have will need maintenance - i.e. updating the forum thread Original Post, or the (new) Docs page. The former is more easily wrangled, but lacks the translations the latter offers. For highly volatile stuff, the forum is a better place.
I think the best compromise we can have here, in line with the suggestion of @LordRalex, is for long-lived issues to be officially documented. If it survives longer than (X period of time), it gets added to the docs page. This allows short-lived incompatibility issues, whether from our end or theirs, to avoid the ignominy of being documented, where

X = { 1 / [ (times asked) + (number of git issues)^2 + (modpacks)^2 ] } x (fudge factor) months

or something like that. Whatever arbitrary margin floats your boat.