codex - 💡(How to fix) Fix 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_hooks is deprecated. Use [features].hooks instead.

The changelog/docs should show:

Before version xx:

[features]
codex_hooks = true

After in version xx:

[features]
hooks = true

This 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.