Better documentation/comunication for feature flags

Feedback
1

Feature: Better documentation/comunication for feature flags like “allow_magiclink_verify_without_session”.

Description:

I have recently had an interaction with the Auth0 Support team to understand the purpose of the “allow_magiclink_verify_without_session” flag, and I was told that:

Feature flags are generally used to hide new features or changes behind an optional flag to help prevent breaking changes and allow customers to opt-in to new features or migrations as they see fit.

The problem with the way these flags have been implemented is that they are not communicated, leaving us to have to guess what the appropriate configuration of our tenants should be in these cases.

Ideally, whenever breaking changes are to be rolled out and feature flags are added to allow opt-out this should be documented, or at least communicated.

Use-case:

In the case of the “allow_magiclink_verify_without_session”, the feature it allows users to opt-out from is an interesting feature.

It was a surprise to me when I retrieved the tenant settings via the Management API and saw that it’s value was set to “true”, meaning that I was opted-out without even knowing.

Teams meticuosly planning the features, and configurations, used within their tenants will definetely want to know about new features, or changes, and how to opt-in or out from them.

2

Effective documentation and communication for feature flags (also known as feature toggles) is crucial for maintaining a seamless development and deployment process, especially in collaborative environments. Here’s a guide on how to improve documentation and communication for feature flags:

**1. Document Feature Flags:

  • Purpose and Use Cases: Clearly define the purpose of each feature flag. Describe the use cases or scenarios where the flag might be used.
  • Description: Provide a brief description of the feature the flag represents and why it’s being introduced.
  • Implementation Details: Explain how the feature flag is implemented, including code snippets or configuration files that are affected.
  • Impact: Document how the flag affects the application’s behavior when enabled or disabled.

**2. Flag Management:

  • Ownership: Assign ownership of each feature flag to specific developers or teams responsible for its implementation and maintenance.
  • Status and Lifespan: Indicate whether a flag is active, inactive, or deprecated. Document planned activation and deactivation dates if applicable.
  • Dependencies: If a flag depends on other flags or components, document those dependencies.

**3. Documentation Platform:

  • Centralized Location: Host your documentation in a central location that’s easily accessible to all team members, such as a wiki, version control system (e.g., Git), or a project management tool.

**4. Communication:

  • Announce New Flags: Notify the relevant teams or stakeholders about the introduction of new feature flags. Share the purpose, benefits, and usage of the new flag.
  • Flag Changes: Communicate any changes made to existing flags, including enabling, disabling, or modifying their behavior.
  • Impact on Users: If a flag impacts end-users, communicate how they might experience changes and whether any action is required from them.

**5. Guidelines:

  • Best Practices: Provide guidelines on how to use feature flags effectively. For instance, when to use feature flags, how to test them, and how to manage technical debt associated with them.
  • Security Considerations: Include security guidelines to ensure that feature flags do not inadvertently expose vulnerabilities.

**6. Versioning:

  • Flag Versions: If you anticipate making changes to a flag’s behavior over time, consider versioning the flags and documenting the changes in each version.

**7. Examples and Use Cases:

  • Code Examples: Provide code examples demonstrating how to implement feature flags in various programming languages and frameworks.
  • Use Case Scenarios: Share specific use cases or scenarios where flags have been particularly useful.

**8. Monitoring and Analytics:

  • Data Collection: If you’re using analytics or monitoring tools to track the performance of flags, document how to access and interpret the data.

**9. Feedback Mechanism:

  • Feedback Loop: Encourage developers and stakeholders to provide feedback on the documentation, especially if they encounter issues or have suggestions for improvements.

**10. Regular Updates:

  • Maintenance: Keep the documentation up to date. When flags are deprecated or removed, update the documentation accordingly.

Remember that effective communication and documentation can help prevent misunderstandings, reduce errors, and ensure a smoother development process. Regularly review and update the documentation to reflect any changes or improvements in your development practices. MyCVSHR

1 Like