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
- 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
.