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.