Experimental Annotation Documentation

In our continuous effort to enhance the Contentsquare Flutter SDK, there are instances where we develop new features that we want to make available to our customers ahead of their official global release. These features are marked as experimental to indicate their status.

The @experimental annotation is an annotation we apply to certain features within the SDK.
This annotation indicates that while the feature is accessible for use, it is not yet fully stable and may undergo changes.
The experimental status allows us to share innovative capabilities with our clients earlier, but it also serves as a caution that the feature is still under evaluation.

Marking a an experimental API is crucial for several reasons:

• API Stability: Although thoroughly tested internally, the API might still evolve based on customer feedback.
• Client Needs: We want to ensure that the feature fully addresses our clients needs before it becomes a permanent part of the SDK.
• Transparency: We want to be transparent about the status of the feature and its potential for change.

Adopting an experimental feature means you are using a feature that could be modified or removed at any time, even without a change in the SDK major version number. While these features grant early access to new functionality, there are important points to consider:

• Logs: When using an experimental feature, you will see a log message indicating that the feature is experimental.
• Risk of Breaking Changes: As these features are still under development, they may undergo significant changes without prior notice.

Experimental features follow one of three potential paths:

If the feature proves successful and meets client needs, it will graduate from experimental status. The annotation will be removed, and the feature will be integrated into the SDK as a stable component.
The documentation and the patch note will be updated to reflect this change.

If the feature is determined to be unnecessary or ineffective, it will quickly move toward deprecation. This process involves marking the feature as @deprecated in the upcoming release, signaling to clients that the feature will no longer be supported. The feature will then be fully removed in the following minor version of the SDK. The documentation will be updated to clearly communicate the deprecation and eventual removal of the feature.

If further development is needed, the feature will remain experimental, with ongoing adjustments to its API, behavior, and scope.

We highly value your input on experimental features, as your feedback plays a crucial role in shaping the final version of these features.
If you’re using an experimental feature, we encourage you to share your experiences, including any issues you encounter, suggestions for improvement, or use cases that the feature supports well.

The most direct way to provide feedback is by submitting a support ticket. When doing so, mention that you are using an experimental feature and provide any relevant details.