docs: canonicalize legacy setting names and update generators by devin-ai-integration[bot] · Pull Request #22503 · PrefectHQ/prefect

devin-ai-integration · 2026-07-14T16:43:56Z

Canonicalizes stale legacy Prefect setting names in docs, source docstrings, shipped profiles, and generated reference artifacts. This update also addresses the five remaining review findings from the initial review.

What changed

P1 — Profile alias precedence. src/prefect/settings/profiles.py now resolves profile settings with canonical-first precedence: canonical keys always win over legacy aliases, and src/prefect/cli/config.py groups and sorts environment/.env aliases deterministically by canonical setting name. prefect config set PREFECT_SERVER_ALLOW_EPHEMERAL_MODE=false now overwrites the canonical key, and prefect config view no longer depends on hash-seed/TOML ordering.
P2 — Pre-3.7 plugin guidance restored. Added the PREFECT_EXPERIMENTS_PLUGINS_ENABLED=true fallback note back to docs/integrations/prefect-azure/index.mdx and docs/v3/advanced/self-hosted.mdx.
P2 — CLI examples restored. Added Examples: sections and guidance to src/prefect/cli/artifact.py, automation.py, block.py, deployment.py, flow_run.py, global_concurrency_limit.py, sdk.py, transfer/_commands.py, and work_pool.py, then regenerated all CLI docs.
P2 — Hidden options filtered again. scripts/generate_cli_docs.py now skips show=False options while still documenting accepted hidden positional arguments (e.g. the automation NAME argument).
P2 — Artifact inspect example fixed. The prefect artifact inspect example now uses --output json for JSON output.
Expanded tests/scripts/test_generate_cli_docs.py to assert the restored examples and hidden-option filtering.

Backward compatibility

Legacy aliases remain accepted at runtime and are still enumerated in:

docs/v3/api-ref/settings-ref.mdx
REST schema supported_environment_variables arrays
release notes and intentional compatibility notes

A final audit found no unintended PREFECT_API_DATABASE_* or PREFECT_API_SERVICES_* occurrences in docs/ or src/integrations/prefect-azure/README.md.

Validation

tests/cli/test_config.py passes.
tests/test_settings.py passes.
tests/scripts/test_generate_cli_docs.py passes.
Markdown-doc tests pass for changed CLI docs (docs/v3/api-ref/cli/).
ruff check / ruff format pass for all changed Python files.
git diff --check is clean.
OpenAPI schema regeneration produces no diff and contains no stale PREFECT_API_DATABASE_* / PREFECT_API_SERVICES_* names.

Checklist

This pull request references any related issue by including "closes <link to issue>"
If this pull request adds or changes functionality, it includes tests or explains why tests are not needed.
If this pull request changes user-facing behavior, it updates documentation or explains why documentation is not needed.
If this pull request removes docs files, it includes redirect settings in mint.json.
If this pull request adds functions or classes, it includes helpful docstrings.

Link to Devin session: https://app.devin.ai/sessions/516ff2ee2924416a8ee6ba376aeb5eb6
Requested by: @desertaxle

- Replace stale legacy env var names in docs, source docstrings, shipped profiles, and test fixtures. - Fix CLI generator for Cyclopts and regenerate CLI docs. - Regenerate Python API reference and OpenAPI schema for affected modules. - Add smoke test for generate_cli_docs.py. Co-authored-by: alex.s <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration · 2026-07-14T16:43:59Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

mintlify · 2026-07-14T16:46:02Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
prefect-oss	🟢 Ready	View Preview	Jul 14, 2026, 4:46 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8839871d87

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-07-14T16:52:04Z

+        if _parameter_is_hidden(meta):
+            continue


Preserve public automation name arguments

Skipping every Cyclopts parameter with show=False also drops public positional arguments that are hidden from CLI help but still accepted, such as prefect automation inspect/resume/pause/delete NAME (src/prefect/cli/automation.py still defines the name parameter). The regenerated automation reference now shows only [OPTIONS], so name-based invocation disappears from the docs; avoid blanket-skipping these public positionals or document them another way.

Useful? React with 👍 / 👎.

Updated scripts/generate_cli_docs.py to keep public positional arguments that are hidden from --help (e.g. prefect automation inspect/resume/pause/delete NAME). Regenerated automation.mdx so those commands now show [OPTIONS] [NAME] and an Arguments section. Addressed in 63ab069.

chatgpt-codex-connector · 2026-07-14T16:52:04Z

+---
+title: " "
+sidebarTitle: prefect plugins
+---


Register the plugins CLI reference page

This new non-hidden page is not added to the CLI Reference list in docs/docs.json (checked the navigation entries around the existing v3/api-ref/cli/worker item). Mintlify sidebar navigation only includes registered pages, so the new prefect plugins command reference will not be discoverable unless v3/api-ref/cli/plugins is added to the nav or the page is hidden/removed.

Useful? React with 👍 / 👎.

Registered v3/api-ref/cli/plugins in the CLI Reference navigation group in docs/docs.json. Addressed in 63ab069.

chatgpt-codex-connector · 2026-07-14T16:52:04Z

+@pytest.fixture(scope="module")
+def generate_cli_docs(script_path: Path):


Add required type hints to the new fixture

tests/AGENTS.md requires full type hints on tests and fixtures, including return type hints on fixtures. This new fixture is untyped and feeds an untyped callable into the test, so it violates the repository's test typing rule; annotate the fixture return value and the test parameter with the callable type.

Useful? React with 👍 / 👎.

Added return-type hint to the fixture (Callable[[str], None]) and annotated the test parameter the same way. Addressed in 63ab069.

codspeed-hq · 2026-07-14T16:57:15Z

Merging this PR will not alter performance

✅ 8 untouched benchmarks
⏩ 1 skipped benchmark¹

_{Comparing devin/legacy-settings-cleanup (9260d88) with main (b749a67)}

1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

…v, type hints - Preserve public positional arguments hidden from --help (e.g. prefect automation NAME). - Include hidden options like --log-output that were in previous generated docs. - Register the new v3/api-ref/cli/plugins page in docs/docs.json. - Add full type hints to the new generate_cli_docs smoke-test fixtures. - Add help text to automation name arguments for generated docs. Co-authored-by: Alex S. <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

Canonicalize legacy Setting objects in _get_settings_fields so canonical and alias env var names map to one Setting, preventing duplicate keys in Profile.settings. Update config view/unset to use canonical names consistently and update test_config.py to use canonical setting names. Canonicalize PREFECT_SERVER_DATABASE_CONNECTION_URL in prefect-azure README. Co-authored-by: Alex S. <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

…LI docs Add durable Examples sections and positional argument help to api, artifact, automation, deployment, events, global-concurrency-limit, and work-pool CLI commands. Update generate_cli_docs.py to trim trailing blank lines from generated MDX files. Expand the generate_cli_docs smoke test to assert METHOD/PATH help, api examples, plugins.mdx generation, and automation NAME argument preservation. Regenerate v3/api-ref/cli/*.mdx. Co-authored-by: Alex S. <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

Apply ruff-format fixes to config, legacy, test_config, and generate_cli_docs smoke test. Co-authored-by: Alex S. <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

…examples, hide hidden options - Canonicalize `_cast_settings` and `prefect config view` env/.env loops so canonical setting names take precedence over legacy aliases and output is deterministic. - Restore pre-3.7 `PREFECT_EXPERIMENTS_PLUGINS_ENABLED=true` guidance to the Azure integration and self-hosting docs. - Add durable CLI examples back into source docstrings for block register, deployment delete, flow-run retry/list, global-concurrency-limit create, sdk generate, transfer, work-pool subcommands, and automation create/update/inspect/pause/resume. - Update `scripts/generate_cli_docs.py` to skip options with `show=False` while still documenting hidden positional arguments (e.g. automation `NAME`). - Correct the `prefect artifact inspect` docstring example to use `--output json` for JSON output. - Regenerate CLI docs and expand `tests/scripts/test_generate_cli_docs.py`. Co-authored-by: Alex S <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

- Test canonical names take precedence over legacy aliases in Profile._cast_settings regardless of TOML input order. - Test config validate persists only the canonical key/value. - Test config view prefers canonical env vars and .env keys over their legacy aliases and falls back to aliases when canonical is missing. Co-authored-by: Alex S <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

devin-ai-integration Bot requested review from chrisguidry, cicdw, desertaxle and zzstoatzz as code owners July 14, 2026 16:43

desertaxle self-assigned this Jul 14, 2026

mintlify Bot deployed to staging - docs July 14, 2026 16:46 View deployment

chatgpt-codex-connector Bot reviewed Jul 14, 2026

View reviewed changes

mintlify Bot deployed to staging - docs July 14, 2026 17:05 View deployment

devin-ai-integration Bot and others added 2 commits July 14, 2026 22:53

mintlify Bot deployed to staging - docs July 14, 2026 22:55 View deployment

devin-ai-integration Bot and others added 2 commits July 14, 2026 23:12

style: ruff format

bd4f6b9

Apply ruff-format fixes to config, legacy, test_config, and generate_cli_docs smoke test. Co-authored-by: Alex S. <alex.s@prefect.io> Co-Authored-By: alex.s <ajstreed1@gmail.com>

mintlify Bot deployed to staging - docs July 15, 2026 17:30 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: canonicalize legacy setting names and update generators#22503

docs: canonicalize legacy setting names and update generators#22503
devin-ai-integration[bot] wants to merge 7 commits into
mainfrom
devin/legacy-settings-cleanup

devin-ai-integration Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

devin-ai-integration Bot commented Jul 14, 2026

Uh oh!

mintlify Bot commented Jul 14, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Uh oh!

codspeed-hq Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@pytest.fixture(scope="module")
		def generate_cli_docs(script_path: Path):

Uh oh!

Conversation

devin-ai-integration Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Backward compatibility

Validation

Checklist

Uh oh!

devin-ai-integration Bot commented Jul 14, 2026

🤖 Devin AI Engineer

Uh oh!

mintlify Bot commented Jul 14, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

codspeed-hq Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

devin-ai-integration Bot commented Jul 14, 2026 •

edited

Loading

codspeed-hq Bot commented Jul 14, 2026 •

edited

Loading