Skip to content

feat(codereadiness): prepare Code Readiness hook specification #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcin11858 wants to merge 2 commits into
base: main
Choose a base branch
from
+25 −0
Open

feat(codereadiness): prepare Code Readiness hook specification #405

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ee0571
feat(codereadiness): prepare Code Readiness hook specification
marcin11858 Jul 3, 2026
bdae242
Merge branch 'main' into feature/codereadiness-hook
marcin11858 Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions specification/appendix-a-included-utilities.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -433,3 +433,28 @@ Consider printing the evaluation context as a stringified JSON object, or using
> If the logger abstraction in the SDK supports a log level concept, the appropriate log level **SHOULD** be used for each stage (before/after: debug/info, error: error).

Consider using `debug` or `info` levels for the `before` and `after` stages, and the `error` level for the `error` stage.

## Code Readiness Hook

The code readiness hook prevents enabling a feature flag in running binaries that are not ready. To protect against runtime errors during rollouts where binaries with different code versions can run, this hook compares the running binary version against a minimum code version defined in `flag metadata`. If the binary version is lower than the minimum code version, the hook throws an error during flag evaluation, causing the SDK to trigger fallback to the default flag value.

This mechanism is particularly useful when evaluating [App Lifecycle Manager feature flags](https://docs.cloud.google.com/saas-runtime/docs/flags/flags-overview) during flag rollouts, ensuring that feature flags requiring newer code cannot be enabled on instances running older binary versions.

The code readiness hook operates during the flag evaluation life-cycle as described below:

| Stage | Behavior |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| before | N/A |
| after | Inspects `flag metadata` for the configured minimum code version key. If running binary version < minimum code version, throws an error. |
| error | N/A |
| finally | N/A |

> The code readiness hook **MUST** be initialized with the running binary version.

> The code readiness hook **SHOULD** support a configurable version key name for finding the minimum code version in `flag metadata` (default key: `minCodeVersion`).

> During the `after` stage, if the running binary version is lower than the minimum code version, the hook **MUST** throw an error.

Throwing an error during the `after` stage triggers fallback to the default flag value, ensuring that features requiring newer code are safely disabled on outdated instances.

> Defaulting to using [Semantic Versioning 2.0.0](https://semver.org/) for comparing versions, the hook **SHOULD** allow configuring different version comparison strategies.
Loading