feat(codereadiness): prepare Code Readiness hook specification

[marcin11858]

This PR

Describes specification of the Code Readiness Hook. The Hook will prevent enabling a feature flag in running binaries that are not ready

Follow-up Tasks

None

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8ddd04df-ce8f-4dcf-b14c-73cb6767bd63

📥 Commits

Reviewing files that changed from the base of the PR and between a235a3e and 3ee0571.

📒 Files selected for processing (1)

• specification/appendix-a-included-utilities.md

---

📝 Walkthrough

Walkthrough

This change adds a new "Code Readiness Hook" specification section to Appendix A, defining requirements for a hook that blocks feature flag activation on binaries below a minimum code version specified in flag metadata, including lifecycle behavior, initialization, and configurable comparison strategy.

Changes

Documentation Addition

Layer / File(s)	Summary
Code Readiness Hook requirements section specification/appendix-a-included-utilities.md	Adds a new section specifying hook behavior for comparing running binary version to a minimum version metadata field, including after-stage error throwing, initialization requirements, configurable metadata key (default minCodeVersion), and default SemVer 2.0.0 comparison strategy.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Code Readiness hook specification.
Description check	✅ Passed	The description is directly related to the PR and matches the Code Readiness Hook specification changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[erka]

Version Compatibility Hook may be another name for it.

[toddbaert]

I can see you are implementing this in a few repos. I'm quite curious about it. Copy pasting my question from here:

What is the main use case for this hook in real-world scenarios? If app-version v2.3.0 has my new feature, why would v2.2.0 of my code have the flag for it? In other words, can you give some examples of when I would have a flag in a version n-1 for a feature that should only be enabled in n? Is it for partially completed features? Like a code-level safety insurance?

I'm not fundamentally opposed to this, but I want to make sure I understand the use case before we add this to the spec - we don't have many hooks in the spec.

If we do want to spec it, we also may want to consider including it in the base SDK - but that's a separate question.

[marcin11858]

I can see you are implementing this in a few repos. I'm quite curious about it. Copy pasting my question from here:

What is the main use case for this hook in real-world scenarios? If app-version v2.3.0 has my new feature, why would v2.2.0 of my code have the flag for it? In other words, can you give some examples of when I would have a flag in a version n-1 for a feature that should only be enabled in n? Is it for partially completed features? Like a code-level safety insurance?

I'm not fundamentally opposed to this, but I want to make sure I understand the use case before we add this to the spec - we don't have many hooks in the spec.

If we do want to spec it, we also may want to consider including it in the base SDK - but that's a separate question.

Thank you for your question. I found two possible use cases:

working on a complex task: The developer introduced reading feature flag in one of the PR but there is more PRs in a queue which are waiting for a review. When all PRs will be merge the code is ready and new feature can be enable safety.
bug in existing application: App-version with a new feature (v2.3.0) was developed but it has a bug. To be sure that any instance of your service will not turn on the feature in app version v2.3.0 the minCodeVersion can be changed to a new version with a fix e.g. v2.3.1. The developer is sure that is impossible to enable new feature in the v2.3.0 app version on any instance.

[oxddr]

Also pasting my reply from open-feature/go-sdk-contrib#904 (comment)

The usefulness of this check is much more apparent with trunk-based development, i.e. single, stable main branch, from which releases are cut on regular basis (e.g. daily or weekly). In this setup, it's common partially completed feature ends up in the new release. This hook is to provide code-level mechanism to prevent enabling those unfinished features. Internally we pair this code-level checks with some other safety mechanisms. This is our last line of defence.

[toddbaert]

@oxddr @marcin11858 OK thanks for the explanations.

Personally, I see the use case - not 100% sure about the name - but the idea of a code-level blocker for a certain feature (distinct from implementing a version check in targeting rules) seems valuable to me; it's a distinct boundary enforced by the code author, rather than whomever might have access to the flag management plane. 👍

However, I question whether or not it really needs to be in the spec, as it seems somewhat niche. I am perfectly OK with having it in all the contribs, and will help to have all instances merged, but we have lots of items in the contribs that are not in the spec. The contribs basically represent extensions from the spec - additional things that we don't specify or include in the SDK.

If you really believe this is important enough to be in the spec, I think we should move the implementations to the SDKs themselves. Things such as the logging hook and in-memory-provider appear in spec appendicies, and due to that they are all included in the SDKs themselves, not the contribs.

What is your feeling about this? Do you think this needs to be in the spec and in the SDKs? Or are you satisfied to maintain it in the contribs as more of an "extension"?

cc @beeme1mr @lukas-reining @erka

[beeme1mr]

What is your feeling about this? Do you think this needs to be in the spec and in the SDKs? Or are you satisfied to maintain it in the contribs as more of an "extension"?

I agree. It's an interesting idea that's likely valuable in some situations. However, it doesn't feel like something that needs to be in the spec. If it turns out to be a highly used feature, we could consider adding it to the spec and possibly even natively supporting it in the SDKs.

[erka]

Link open-feature/java-sdk-contrib#1819 as well to this.

[oxddr]

We don't have strong preferences to have this in the spec. I believe it was suggested to put it here during one of code reviews. For us it's fine to have the implementation in languages we're interested about and treat it like extension, similarly to lots of other hooks.

I think it may be worthy to put this description somewhere (maybe alongside one of the implementations), so whenever someone wants to contribute the implementation in other languages, we can make them follow the same spec for sake of consistency.

[erka]

The OpenTelemetry hook is in go-sdk-contrib, and it has its own Appendix D, so it really depends on how important this is. If this hook is implemented across several SDKs, it would be better to have a common reference point for all of them.

I think this PR is a great starting point for establishing a shared vision for this hook, even if it isn't merged and remains open for a while. Just my two cents.

[toddbaert]

The OpenTelemetry hook is in go-sdk-contrib, and it has its own Appendix D, so it really depends on how important this is. If this hook is implemented across several SDKs, it would be better to have a common reference point for all of them.

We have some telemetry-related helpers and constants in various SDKs, which are related to appendix D, for example: https://github.com/open-feature/js-sdk/blob/main/packages/shared/src/telemetry/attributes.ts - these are intended to be used for hooks etc, so there is at least some representation of appendix D in SDKs directly (we don't want to add the OTel API as a dep in the SDK itself).

I think this PR is a great starting point for establishing a shared vision for this hook, even if it isn't merged and remains open for a while. Just my two cents.

Ya I agree - and to be clear, I'm not opposed to adding it if there's enough interest. Let's continue with the implementations for now, and we can revisit later if we actually want to specify this.