09/06 2016

Bugs - core or Flux?

It can be difficult to determine if bugs you encounter are caused by Flux or TYPO3 - this article aims to help you tell the difference so bugs get reported to the right place.

Dear developers,

We get a lot of bug reports which concern TYPO3 rather than our extensions - which is understandable since most of the extensions are integrations with TYPO3 features. Those bug reports with wrong addresses are the motivation for writing this article but please don't take it as us trying to push your issues away or even just complain about users reporting bugs. It's quite the opposite - the intention is first and foremost to help you as users get (quick) solutions to your problems and questions for your answers from the right source.

FluidTYPO3 gives you easy access to features that are normally hard to integrate with in TYPO3 - which means that FluidTYPO3 often exposes TYPO3 bugs before other users see them, causing those bugs to be identified incorrectly as FluidTYPO3 bugs.

This doesn't mean you're not allowed ask us about such bugs, of course not. But please do so on the support chat instead of opening issues if you're in doubt ;)

Which types of bug reports should be reported to FluidTYPO3?

In general we only accept bug reports where the bug fulfils the following requirements:

1. Reproducible on current LTS and/or most recent TYPO3 release. We no longer accept reports for issues reproduced on 6.2 but we do accept pull requests with patches for 6.2 on the "legacy" branch.
2. Not already described in an open bug report. Please make sure the issue you report isn't already reported in both open and closed issues. If already reported and closed, you usually find thorough explanations in the issue comments. If already reported and open, subscribe to that issue and if you can, add any info you may have.
   

Use the convenient <link https: github.com external-link-new-window>global open and closed issues lists for a list of every issue in every FluidTYPO3 extension when you need to check if your issue is already reported.

Checklist: is it a FluidTYPO3 / Flux bug?

If your issue matches anything on this list it is, with some exceptions where noted, an issue you should report to FluidTYPO3.

1. Are you getting unexpected output from VHS ViewHelpers? In most cases YES, it would be a FluidTYPO3 issue. Unexpected output from Flux ViewHelpers is a different beast - almost all Flux ViewHelpers do not generate any output so any issues with HTML, JS or CSS of form components usually points to incorrect usage (bad argument combinations). To make sure you're using the arguments correctly please refer to the official TYPO3 TCA documentation first, then ask us on the support chat if/where to report a possible issue.
2. Are you getting an error or exception caused by a class in the FluidTYPO3 vendor namespace? Then most likely YES. Examples of such errors could be Exceptions thrown by a ViewHelper class in Flux, PHP errors caused by incorrect parameters, incompatibility between FluidTYPO3 and TYPO3 and similar. All of which indicate that we in FluidTYPO3 need to take care of the issue. Note that you may need to inspect server error logs to find such PHP errors (the infamous white screen of death 500 error)!
3. Are your Flux components displaying incorrectly visually, e.g. form fields not respecting your parameters, type of field not as expected, error displayed in place of field/component? Then YES, this indicates Flux might be generating incorrect configuration arrays.
4. Is the data you save being treated incorrectly, ignored, malformed or otherwise not work as expected? Then most likely NO - this would indicate that TYPO3 is not capable of handling the input data and it is likely we cannot work around it. In this context, don't forget about the possible MAX_POST_VARS and other PHP configuration parameters which need to be sufficiently high to accommodate large forms (with many fields).
5. Is nested content, versions, workspaces etc. not behaving correctly for FluidTYPO3-based content? Then YES this is most likely a FluidTYPO3 / Flux issue which we need to take care of. There are exceptions to this but please report issues to us; we may tell you it needs to be reported to TYPO3 instead but in most cases we would handle it.
6. Are you getting errors specific to the TCEforms array that gets generated (e.g. warnings about invalid properties or missing properties)? Then both YES and NO - meaning you should report such issues both to us and to TYPO3. We may be able to create workarounds until the TYPO3 core contributors pick up and fix the issue.

Some examples of TYPO3 problems that are frequently mistaken for FluidTYPO3 / Flux issues:

• FormEngine regressions and breaking changes - in TYPO3 the entire engine that configures and renders TCEforms (which is what Flux integrates with) has been replaced and is continually being improved upon. This results in sometimes changing requirements and capabilities of the TCEforms engine itself, the symptoms of which often get mistaken for Flux issues. Unfortunately such regressions have also snuck into LTS branches of TYPO3 and may be caused even with bug fix patchlevels. Most importantly: if this happens in a bug fix patchlevel you must report it as a regression to TYPO3. If it happens with a minor/major upgrade please report it to us since it may indicate a compatibility issue.
• Regressions in other TYPO3 code causing unexpected errors. Because TYPO3 is in the process of cleaning up and improving several classes' public APIs sometimes code gets implemented in ways that require additional initialisation for the class to work. When these sorts of regressions appear in bug fix patch levels they must be reported to the TYPO3 core. We like to hear about such issues but please discuss them with us on the support chat instead of creating issues. If a regression is important enough we will create an issue for it and link it to the TYPO3 issue.
• Issues caused by TYPO3 preferring one type of environment over others (e.g. Apache with .htaccess being heavily used). Some deprecations in TYPO3 are taking place via URL redirects and some of the most affected component types are TCA wizards and popup windows. If you get 404 errors when trying to use Flux components in the UI this looks like a Flux error but may be caused by choice of web server.

The list above is not exhaustive and maybe updated in the future. Hopefully it gives a good impression of the factors that determine if an issue should be reported to FluidTYPO3.

Checklist: is it a TYPO3 bug?

If your issue matches any on this list it almost always is a TYPO3 issue:

1. Is the issue known on the TYPO3 core bug tracker? Then by definition YES; unless that issue is rejected with an explanation that says the problem is with the integration (Flux, VHS etc.). If an open/unresolved TYPO3 issue exists please do not create these as bug reports for FluidTYPO3. Instead and if you are able, add whatever info you may have to the TYPO3 issue: steps to reproduce, screenshots of errors, additional info from logs, etc.
2. Does the same problem appear in other places not using FluidTYPO3 features? Although it can be hard to do, we greatly appreciate if you try to reproduce issues with for example Flux components by creating a similar FlexForm using the traditional approach. In almost all cases where you can reproduce the issue this way: YES, the issue appears be a regression in TYPO3.
3. Is the problem introduced by upgrading TYPO3 to a bug fix patchlevel (e.g. not upgrading the major/minor version)? Then YES, this exclusively indicates a regression that must be reported to TYPO3, also if it only happens in for example a Flux or VHS class.

For all of the above we appreciate if you don't create FluidTYPO3 issues, but you are of course welcome to discuss the bugs with us on the support chat.

We greatly appreciate it if you spend a bit of time evaluating the issue you are going to report, using the criteria above. In particular if you locate an already open issue it is a lot easier for both teams to handle the mass of reports if you subscribe and add your info to the open issue instead of opening a new one. Opening new issues when one exists only adds to the difficulty other users will have finding any open/closed issues.

Searching closed issues also yields results for fixes that are queued to be released - with links for you to download a patch if you need to emergency patch your TYPO3 core or FluidTYPO3 extensions. In those cases you save the time it takes to report your issue and potentially get an immediate fix; and you save time for the teams who handle the reports. We feel confident enough to say this also on behalf of the TYPO3 team.

Thank you for taking these things into consideration! Let's help each other to be more efficient ;)

Kind regards,
The FluidTYPO3 team