Improve Codex CLI release management: changelogs, prerelease notes, docs sync, and migration examples
I would like to raise a broader concern about the Codex CLI release process.
This is just one example: in Codex CLI 0.129.0, the CLI now warns that [features].codex_hooks is deprecated and that users should use [features].hooks instead, while parts of the documentation still appear to reference the old configuration key.
That specific issue is easy to fix, but it points to a larger problem: the release cycle for Codex CLI does not currently feel sufficiently reliable or transparent for users who depend on it in real development workflows.
Main issues
1. Documentation appears to lag behind actual CLI behavior
When the CLI introduces or deprecates configuration options, the documentation should be updated at the same time as the release.
This is especially important for features such as hooks, sandboxing, approvals, and config flags, because they affect security, automation, and day-to-day developer workflows.
2. Prereleases often lack useful changelog information
There are prerelease versions available, but in many cases there does not appear to be meaningful changelog or release-note text explaining what changed.
That makes prereleases hard to evaluate. Users cannot easily decide whether a prerelease contains an important fix, a breaking change, a security-related change, or just internal work.
3. The changelog and release notes should be part of the release, not an afterthought
For a CLI tool used in serious development environments, each release should clearly document:
- Added features
- Changed behavior
- Deprecated options
- Breaking changes
- Migration steps
- Security-relevant changes
- Known issues
- Whether the release is stable or prerelease-quality
4. Deprecations and behavior changes need concrete before/after examples
For every user-facing change, especially config changes, command changes, hook changes, sandbox/approval changes, or changed defaults, the release notes should include concrete examples showing how it worked before and how it should be done in the new version.
For example, instead of only saying:
[features].codex_hooksis deprecated. Use[features].hooksinstead.
The changelog/docs should show:
Before version xx:
[features]
codex_hooks = trueAfter in version xx:
[features]
hooks = trueThis kind of side-by-side migration example makes it immediately clear what users need to fix. Without it, users have to guess, search the docs, inspect config files, or infer behavior from warnings.
5. Deprecations need clear migration guidance
If a config key changes from [features].codex_hooks to [features].hooks, the docs, config reference, CLI warning, and changelog should all say the same thing.
Ideally, the changelog should also state whether the old key is still accepted as a legacy alias, how long it will continue to work, and what users should change in their config.
Expected behavior
The release process should ensure that every Codex CLI release, including prereleases, has:
- Accurate release notes
- A meaningful changelog entry
- Updated documentation for changed user-facing behavior
- Clear migration instructions for renamed or deprecated config options
- Concrete before/after examples for every changed config, command, or behavior
- Consistency between CLI warnings, docs, config reference, and changelog
Actual behavior
- CLI behavior and documentation can be out of sync
- Prereleases may have little or no useful changelog information
- Users must infer important changes from warnings, commits, or trial and error
- Configuration changes can be confusing even when the CLI itself knows what the replacement should be
- Users are not always given concrete before/after examples showing exactly what to change
Why this matters
Codex CLI is not just a toy tool. It is used to modify code, run commands, automate development workflows, and integrate with local environments. If OpenAI wants Codex to be trusted in professional or enterprise-style workflows, release discipline needs to be stronger.
Good release management is not optional for this kind of tool. Users need to understand what changed before they update, especially when the changes affect configuration, hooks, approvals, sandboxing, or automation.
Please consider tightening the Codex CLI release process so that changelogs, prerelease notes, documentation, CLI behavior, and migration examples stay synchronized.
7 Comments
Potential duplicates detected. Please review them and close your issue if it is a duplicate.
Powered by Codex Action
A slightly ironic but serious point:
OpenAI is, after all, an AI company. This seems like exactly the kind of release-management problem where AI could be used internally to reduce friction.
For example, whenever a user-facing change is merged, an internal AI-assisted release checklist could automatically verify things like:
The point is not that AI should replace human release ownership. The point is that this is exactly the kind of repetitive consistency work AI should be very good at helping with.
If Codex can help users refactor, inspect codebases, and automate development tasks, then surely OpenAI can also use similar tooling internally to catch documentation drift, missing prerelease notes, inconsistent config examples, and incomplete migration guidance before releases go out.
This would make the release process feel much more professional and would also demonstrate confidence in the very toolchain OpenAI is asking developers to trust.
@github-actions:
Thanks for the duplicate check.
I reviewed #20784. It is related, but I do not think this issue is a duplicate.
#20784 appears to focus mainly on version numbering policy and missing version numbers.
This issue is broader. It is about the Codex CLI release process as a whole, including:
The hooks example is only one concrete symptom. The main request here is for a more reliable release-management process, not just an explanation of version numbering.
This issue appears to be another concrete example of the broader release-process problem described here:
https://github.com/openai/codex/issues/21639
That issue reports hooks working in
0.128but no longer running in0.129, using the previous hook configuration style.To me, this illustrates the same release-management problem from the other direction:
This is why I think the issue here should remain broader than just one config key. The concrete hooks case is a symptom of a larger need for better release notes, prerelease changelogs, migration examples, and docs synchronization.
Please refer to our feature maturity designations. Codex hooks are in the experimental stage. Changes at this stage should be expected. Once a feature reaches the "stable" level of maturity, we are much more careful about breaking changes, and removal of stable features goes through a more formalized deprecation process.
@etraut-openai, thanks for the reply.
I think there may be a misunderstanding here. My issue was not really about Codex hooks per se, nor about whether experimental features are allowed to change.
I fully understand that experimental features may change, break, or be redesigned. That is reasonable.
The point of the issue was broader: even when a feature is experimental, the release process should still make it clear what changed, what users are expected to do, and where the current documentation/examples match the actual CLI behavior.
Feature maturity explains why breaking changes may happen. It should not be used as a reason to avoid improving changelogs, prerelease notes, documentation synchronization, or migration examples.
In fact, experimental features arguably need even clearer release notes, because users already know the surface may change. The problem is not that it changed — the problem is when users have to infer the change from warnings, stale docs, missing prerelease notes, or trial and error.
To avoid confusion, I will open a new issue that does not use hooks as the main example, since that seems to have made the broader release-process concern look like a hooks-specific complaint.
The Supported features table on the Config Basics page lists the feature
codex_hookswith thestablematurity.codex_hookscannot be kept for backwards compatibilityAnd please, fix your documentation.
<img width="902" height="519" alt="Image" src="https://github.com/user-attachments/assets/e98c0adc-2ade-41b1-8d11-f5745792856c" />