I am thinking about caching and filters.
In 3.0, we cache instances of Filter by using @FullTextFilterDef.cache=true
In 3.1, we still can cache instances of Filter using @FullTextFilterDef(cache=true, cacheBitResult= CacheBitResults.NO)
an we can cache BitSet results by using @FullTextFilterDef(cache=true) //, cacheBitResult= CacheBitResults.AUTOMATIC

I think we introduced cacheBitResult to keep @FullTextFilterDef backward compatible. But reality is that this feature is not backward compatible:
 - a new layer of caching is automatically added if you keep the annotation as in 3.0. It probably won't do too much harm but add an unnecessary indirection

Fundamentally, it seems that the annotation should be 
@FullTextFilterDef(cache=FilterCacheMode.RESULTS)
@FullTextFilterDef(cache=FilterCacheMode.FILTER_INSTANCE)
@FullTextFilterDef(cache=FilterCacheMode.NO)

This will force a change from 3.0 apps to 3.1 apps but it's much clearer.
I can't seem to find a compelling reason to have instance caching and result caching configurable independently.

WDYT?