This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Working in released version

Generally, when implementing a new feature, we have the following possible strategies:

• Implement it in master only

  • If the feature breaks anything, it only breaks our test installations and we have the development cycle to notice it.

• Implement it in a customer module only

  • If the feature breaks anything, it only breaks the installations of the customer that ordered the feature.

• Implement it in a released version if it does not endanger any customers on that or later version

  • Careful when deciding if a feature is harmless or not, be sure you understand all implications. Maybe ask a colleague to be certain.

• Implement it in a released version with Feature Flags

  • If it breaks anything and you used feature flags properly, you can simply disable the feature.

  • You might want to use feature flags even when developing in master or a customer module, if you’re unsure if the previous behaviour might still be needed.

• Implement it in a new Custom Branch

  • If the feature breaks anything, it only breaks the installations on that specific branch.

• Otherwise, do not implement it

Feature Flags

Feature flags allow us to enable or disable changes in our software. The intent is to allow changes to be implemented with the possibility of quickly reverting them without a deployment if the have unintended side effects. This chapter shall serve as a guide on how and when to implement feature flags in the different parts of the Nice framework.

When a feature flag is disabled, the system should behave exactly as if the changes were not implemented at all. Make sure to document what exactly your feature flag controls.

Once you’ve committed and merged your feature flag, consider creating a new Jira issue to remove the feature flag in some future version, unless this is supposed to be a permanent switch.

Data model

No feature flags possible. If you need to change the data model, keep to nullable fields and relations. Never remove fields or relations.

Forms & Textresources

No feature flags possible. You might be able to use a FormInterceptor that only runs when your feature flag is active to achieve your desired outcome.

ACL

No feature flags possible. If you need to adjust existing rules, you might need to consider writing your own PolicyProcessor, and use feature flags in there.

Backend logic

Feature flags can be implemented as simple Spring properties. Depending on where you need the flag, you’ll need to access them in different ways.

If you need to replace an entire component or you are only adding new components, you can use the @ConditionalOnProperty annotation and simple enable / disable the component based on your feature flag.

When you need to change only a smaller bit of logic in a component, you can let Spring inject the property in your component by using the @Value annotation. Alternatively, you can aquire a Environment object and read properties from there.

If you need to read a feature flag somewhere that is further from a Spring connected component, you might need to pass the flag down the call stack. Alternatively, we could create a service that gathers feature flags and allow static access to them. This has not been implemented so far, feel free to do so when necessary and then document it here.

Frontend logic

Spring properties can also be accessed in the frontend, once they have been whitelisted in the backend. To do that, create a Spring bean annotated with @PropertyWhiteList, afterwards it can be loaded through the /client/property endpoint.

Custom Branch

Warning

This should only be used as a last resort. It requires additional resources and effort, and complicates our CI setups. It needs to be properly planned and set up. Make sure to discuss with PL, BS and DEV teams.

Just like we create branches for our released versions, we are able to create custom branches that contain changes we deem to risky for our regular branches. These will usually branch of some older released version, get developed and tested until finalized, and then merged back into master.