Open EdX: Preparing For FEATURES Dictionary Removal

Aug 19, 2025 by Felix Dubois 52 views

[DEPR]: Preparing for the Removal of the Writable FEATURES Dictionary in Open edX

Hey everyone! Today, we're diving deep into an important deprecation plan (DEPR) for Open edX: the removal of the FEATURES dictionary as a writable settings container. This is a significant change aimed at improving clarity, consistency, and manageability within the platform's settings. Let's break down what this means for you, why it's happening, and how to prepare for it.

Rationale Behind the Change

Clarity and Consistency in Feature Flag Management

The primary reason for this change revolves around making feature flag management in Open edX more transparent and straightforward. Historically, the FEATURES dictionary in Django settings has acted as a mutable container for these flags. While seemingly convenient, this approach has led to several issues. Specifically, the use of the FEATURES dictionary has blurred the lines between top-level settings and dictionary keys, creating confusion and complicating operator configurations.

Feature flags are crucial for controlling the behavior of your Open edX platform, allowing you to enable or disable specific functionalities. By treating them as top-level settings, we ensure they are explicitly defined and easily discoverable. This enhances the overall maintainability and understanding of your platform's configuration. Moreover, having feature flags as top-level settings simplifies the process of overriding these flags in different environments (e.g., development, staging, production). You can leverage Django's built-in settings overriding mechanisms without the need to delve into nested dictionary structures. The move to top-level settings also promotes a more standardized approach to configuration management. It aligns with best practices in Django development and ensures that feature flags are treated with the same importance as other critical settings. This consistency reduces the cognitive load on operators and developers, making it easier to reason about the platform's configuration. Ultimately, the goal is to provide a more robust and intuitive way to manage feature flags in Open edX. This change will empower operators to better control their platform's features and ensure a smoother experience for learners.

What's Changing?

Deprecating Write Access to the `FEATURES` Dictionary

So, what exactly is being removed? The core change is the deprecation of writing to the FEATURES dictionary directly within your settings files. Think of it this way: previously, you might have adjusted feature flags using lines like FEATURES['ENABLE_FOO'] = True. This method is now being phased out. Additionally, the use of FEATURES keys in YAML files without corresponding top-level settings will also be deprecated. This means that if you have feature flags defined only within the FEATURES dictionary in your YAML configuration, you'll need to make adjustments.

Instead of directly modifying the FEATURES dictionary, the replacement approach involves defining all feature flags as top-level settings. This applies both in your YAML configuration files and in your Python settings. Imagine feature flags as individual light switches, each with its own clear label and function, rather than being bundled together in a single, less transparent box. This approach will lead to a more organized and maintainable settings structure. Defining feature flags as top-level settings provides better visibility and control over your platform's features. It simplifies the process of understanding which features are enabled or disabled, making it easier to troubleshoot issues and manage your Open edX instance. The transition to top-level settings also aligns with the broader Django ecosystem, where settings are typically defined at the top level for clarity and ease of use. This consistency reduces the learning curve for new developers and operators and makes it easier to integrate Open edX with other Django-based applications. While FEATURES will temporarily exist as a read-through dictionary for backward compatibility, any attempts to write to it will trigger warnings. This is your signal to update your configuration and adopt the new approach. The ultimate goal is to ensure a smoother and more predictable configuration experience for everyone using Open edX.

Transition Instructions for Operators

How to Prepare for the Change

Don't worry, guys, this isn't a sudden switch! We're providing clear instructions to help you transition smoothly. The first step involves updating your YAML files. For every key within the FEATURES dictionary, you need to duplicate it as a top-level value. Let's say you have something like this in your YAML:

FEATURES:
 ENABLE_FOO: true

You'll need to modify it to look like this:

FEATURES:
 ENABLE_FOO: true
ENABLE_FOO: true

See? Simple duplication! Next up, if you have any custom Python settings where you're setting FEATURES keys, you'll need to do something similar. Whenever you set a FEATURES key, also set the corresponding top-level setting. For example, if you have:

FEATURES['ENABLE_BAR'] = False

Change it to:

FEATURES['ENABLE_BAR'] = False
ENABLE_BAR = False

This ensures that the feature flag is set both within the legacy FEATURES dictionary (for now) and as a top-level setting. By duplicating the settings, you ensure that your platform continues to function as expected during the transition period. This approach allows you to gradually adopt the new configuration style without disrupting your existing workflows. The warnings generated when writing to FEATURES will serve as helpful reminders to complete the migration. Remember, these warnings are there to guide you and ensure that you're fully prepared for the eventual removal of write capability from FEATURES. Taking these steps proactively will save you time and effort in the long run. It will also contribute to a cleaner and more maintainable Open edX configuration. This transition is about more than just changing settings; it's about adopting a more robust and consistent approach to feature flag management in Open edX.

Key Dates and Timeline

Important Milestones for the Deprecation

To give you a clear picture of the timeline, here are some key dates to keep in mind. While the RFC (Request for Comments) has already been accepted, and the transition is already unblocked, the earliest breaking changes are slated for August 26, 2025. This gives you a significant window to make the necessary adjustments. Before this date, we will be adding warnings when writing to FEATURES to help you identify areas that need updating. We'll also be updating the operator documentation with detailed migration steps to guide you through the process. This documentation will serve as your go-to resource for understanding the changes and implementing them effectively. The implementation of the DerivedDict for FEATURES is also a crucial step, ensuring that it functions as a read-through dictionary for backward compatibility. This allows you to continue reading feature flags from the FEATURES dictionary while you're transitioning to top-level settings. A comprehensive sweep of the edx-platform codebase will be conducted to identify all references to FEATURES[...] and migrate them to top-level settings. This ensures that the platform itself is fully aligned with the new approach. After these steps are completed, the write capability will be removed from FEATURES. This is the point where attempting to write to the FEATURES dictionary will no longer be allowed. Finally, in a future release, the FEATURES dictionary will be fully removed. This marks the completion of the deprecation process and the full adoption of top-level settings for feature flags. By providing this timeline, we aim to give you ample time to plan and execute the necessary changes. We encourage you to start the transition process as soon as possible to ensure a smooth upgrade experience.

Task List

Steps to Completion

Here’s a breakdown of the tasks involved in this deprecation process:

- [ ] Add warnings when writing to `FEATURES`
- [ ] Update operator documentation with migration steps
- [ ] Land DerivedDict implementation of `FEATURES`
- [ ] Sweep edx-platform codebase for references to `FEATURES[...]` and migrate to top-level settings
- [ ] Remove write capability from `FEATURES`
- [ ] Fully remove `FEATURES` in a future release

This list provides a clear roadmap of the steps being taken to implement the deprecation. Each item represents a significant milestone in the process. The addition of warnings when writing to FEATURES is a crucial feedback mechanism, alerting operators to potential issues. The updated operator documentation will provide comprehensive guidance on how to migrate to the new approach. The DerivedDict implementation ensures backward compatibility during the transition period. The codebase sweep and migration to top-level settings ensures that the platform itself is fully aligned with the new configuration style. The removal of write capability and the eventual full removal of FEATURES mark the final stages of the deprecation process. By tracking these tasks, you can stay informed about the progress of the deprecation and anticipate any potential impacts on your Open edX deployment. We are committed to transparency and will keep you updated on the status of each task.

Conclusion

Embracing a Clearer Future for Open edX Settings

This deprecation is a crucial step towards a more maintainable and understandable Open edX platform. By moving feature flags to top-level settings, we're enhancing clarity, consistency, and control for operators. Remember to follow the transition instructions and stay tuned for further updates. Thanks for being part of the Open edX community, guys, and let's make this transition as smooth as possible! This change reflects our ongoing commitment to improving the Open edX platform and providing you with the best possible experience. The move to top-level settings is not just a technical change; it's a step towards a more robust, predictable, and user-friendly configuration system. We believe that this enhancement will empower you to better manage your Open edX deployments and deliver exceptional learning experiences to your users. Your feedback is invaluable to us, so please don't hesitate to reach out with any questions or concerns you may have. We are here to support you throughout this transition and ensure that you have the resources you need to succeed. Together, we can continue to evolve the Open edX platform and make it even better for learners around the world. By embracing these changes, we are building a stronger foundation for the future of online education.