[Mohamedajab]

Description

Add tips for adopting Black in an existing project: consistent configuration, formatting-only commits, automated checks, and coordinating active branches. Present alternatives rather than prescribing one rollout process.

Closes #967.

Checklist

• Documentation updated; no code-style or runtime changes.
• Changelog entry added for Expand guidance for adopting Black in existing projects #5472.

Validation

The changed file passes pre-commit, including Prettier, and git diff --check. The Sphinx build rendered the updated page but could not complete locally because the existing blackd --help program-output command is not on PATH. I have not claimed a successful full docs build for this revision.

[cobaltt7]

LGTM, welcoming input from other maintainers

[cobaltt7]

Had another thought: could you mention --skip-string-normalization in this section as well?

If you are adopting Black in a large project with pre-existing string conventions
(like the popular
"single quotes for data, double quotes for human-readable strings"),
you can pass --skip-string-normalization on the command line. This is meant as an
adoption helper, avoid using this for new projects.

- from "The Black Code Style" docs

[Mohamedajab]

Thanks — I added the --skip-string-normalization adoption guidance and merged current main, resolving the conflict. The focused pre-commit checks pass.

The refreshed changelog job is failing even though CHANGES.md contains the required (#5472) entry. Its log shows the new grep -Pz '...\)$' expression failing to match that normal non-final changelog line. Could a maintainer apply the ci: skip news label or adjust the workflow check? I have left the changelog in its valid Unreleased → Documentation section rather than moving it solely to satisfy the broken match.