🚀 New Features

• There is now support for the Poetry backend in usethis. Access it via the --backend=poetry option for applicable commands.
• Tools which add formatters (usethis format, usethis tool pyproject-fmt, and usethis tool ruff) will now automatically apply the formatter to the project when added.
• There is now a usethis tool tach command to add the Tach architecture tool to the project.
• usethis tool commands now support a --no-hook flag to opt out of modifying git hook configuration (e.g. in .pre-commit-config.yaml) when managing the tool.
• usethis show commands now support an --output-file option to write the output to a file instead of printing it to the console.
• There is now a usethis show license command to show the license of the current project.
• There is now a usethis badge bitbucket command to add a badge for Bitbucket usage to the README.
• usethis tool pytest and usethis test will now automatically add an example test file. This helps ensure that pytest will run out-of-the-box without emitting a non-zero error code.

🐞 Bug Fixes

• In some cases, when usethis modified TOML files, comments would be stripped from multi-line lists. This has been fixed.
• Out-of-schema entries in .pre-commit-config.yaml files will no longer result in errors when being handled by usethis. This is especially useful for prek users, since prek extends .pre-commit-config.yaml with support for additional configuration options which are not found in the standard pre-commit schema.

🦾 Robustness

• Hard-wrapping is now disabled for CLI outputs.
• The usethis tool requirements.txt command now uses a more standard URI-based pre-commit hook for exporting (using the astral-sh/uv-pre-commit repo) instead of a local system hook.
• Default code coverage configuration now excludes the pattern msg = ["'] associated with writing error messages outside the error class (see the EM101 Ruff rule).
• The heuristic for detecting uv usage will now check whether uv is declared as a dependency (including as a dev dependency) in pyproject.toml when the file exists, in addition to the previous heuristics. This should help reduce false positives for projects which use other tools but have pyproject.toml files with no uv configuration.
• There is improved handling of pre-commit configuration validation for when the hook ID is null.

📚 Documentation

• The usethis show sonarqube command is now documented explicitly in the CLI reference section of the documentation site.
• The concept of backends is now expounded on the documentation site.
• All modules now have module docstrings.
• The project description and keywords have been updated to reflect the current state of the project. The license Trove classifier has been removed since Trove classifiers for licenses are no longer recommended.
• The FAQ page has been re-structured.
• The pipeweld utility now has more comprehensive docstrings.
• The FileManager and files_manager objects now have more detailed docstrings.

📦 Packaging

• The identify package is a new dependency to provide support for the usethis show license command.

🔧 Internal Changes

• There is improved type compliance, especially for the implementation of the file management system.
• Ruff configuration now resides in ruff.toml for development.
• There is now a PreCommitConfig.from_system_hook method to simplify the specification of pre-commit hook configuration for the various tools.
• Agent configuration and bespoke prek hooks continue to be developed.

What's Changed

• Add requests to the dev dep bump workflow by @Copilot in #1548
• Create skills registry in AGENTS.md with validation hook by @Copilot in #1532
• Bump requests for development by @github-actions[bot] in #1552
• Add usethis-cli-modify agent skill by @Copilot in #1555
• 1556 add config for external agent skills by @nathanjmcdougall in #1557
• Validate lockfile remains unchanged during copilot setup, add npm cac… by @nathanjmcdougall in #1560
• Document usethis show sonarqube more thoroughly by @Copilot in #1562
• Add the vercel-labs/skills/skills/find-skills skill by @nathanjmcdougall in #1569
• Try and capture lessons + skill tweaks automatically via AGENTS.md by @nathanjmcdougall in #1571
• Document the npx skills option --skill by @nathanjmcdougall in #1570
• Add concise documentation guidance to usethis-cli-modify skill by @Copilot in #1578
• Add --output-file option to usethis show commands by @Copilot in #1565
• Add --no-hook flag to all usethis tool subcommands by @Copilot in #1558
• Add module docstrings and set up automated export of docs/module-tree.txt. by @nathanjmcdougall in #1579
• Clarify that files modified in prek runs are still failures by @Copilot in #1580
• Add sync framework for inheriting content into AGENTS.md by @Copilot in #1581
• Test markdown validity after usethis badge calls by @Copilot in #1584
• Move test suite structure expectations into a prek hook by @Copilot in #1583
• Enable reportAssignmentType in basedpyright by @nathanjmcdougall in #1585
• Enable reportMissingParameterType in basedpyright by @nathanjmcdougall in #1586
• Introduce covariant DocumentProtocol to enable `reportMissingTypeAr… by @nathanjmcdougall in #1588
• Add usethis badge bitbucket command by @Copilot in #1590
• Move Ruff configuration from pyproject.toml to ruff.toml by @Copilot in #1592
• Use URI repo for uv-pre-commit hook in requirements.txt tool by @Copilot in #1589
• Add msg = ["'] to coverage.py exclude_also patterns by @Copilot in #1593
• Deduplicate test_latest_version tests via parametrize by @Copilot in #1596
• Emphasize static checks must run for all changes including small follow-ups by @Copilot in #1604
• Put more emphasis on reporting skills usage etc. by moving module-tre… by @nathanjmcdougall in #1613
• Agent config: emphasize writing tests with full coverage by @Copilot in #1612
• Add usethis-github-issue-create agent skill by @Copilot in #1610
• Rename usethis-test-with-coverage to usethis-python-test-full-coverage by @Copilot in #1620
• Agent config: Record lessons as GitHub issues instead of directly editing skills by @Copilot in #1618
• Add agent instruction to reference issue IDs in PR descriptions by @Copilot in #1615
• Run static checks workflow for doc-only changes by @Copilot in #1617
• Add PreCommitConfig.from_system_hook() to deduplicate backend dispatch in tool specs by @Copilot in #1606
• Fix TOML comment stripping in extend_list and remove_from_list by @Copilot in #1591
• Add YAGNI for function parameters to usethis-python-functions skill by @Copilot in #1622
• Add layer-awareness guidance to test-affected-find skill by @Copilot in #1623
• Add function placement principles to usethis-python-code skill by @Copilot in #1629
• Bump pygments for development by @github-actions[bot] in #1631
• Add guidance on keeping skill descriptions general by @Copilot in #1635
• Add global config pass-through avoidance guidance to function design skill by @Copilot in #1638
• Add usethis-agents skill with auto-generated skills directory by @Copilot in #1630
• Add function reference to AGENTS.md with auto-generated docs/functions.txt by @Copilot in #1624
• Remove spacing between bullet points in changelog by @nathanjmcdougall in https://github.com/uset...

💥 Changes

• The usethis ci command (and usethis ci bitbucket subcommand) has been removed, including all related code and documentation. The rationale is documented at this page of the documentation site; also see #1313.
• The --pre-commit option for usethis init has been renamed to --hook to be more general and to align with the new usethis hook command. This is partly in view of providing support for other Git hook tools in the future (specifically; prek).

🚀 New Features

• There is now a usethis tool ty command to manage the ty type checker from Astral. There is also a higher-level usethis typecheck command which has the same effect, and an opt-in --typecheck option for usethis init. There is also an associated usethis badge ty command to add a badge for ty to the README.
• There is now a usethis arch command to manage architecture analysis tools such as Import Linter; currently this wraps usethis tool import-linter. There is also an opt-in --arch option for usethis init.
• There is now a usethis hook command to manage Git hook tools; currently this wraps usethis tool pre-commit. There is also an opt-in --hook option for usethis init.
• usethis init now accepts a --build-backend option to specify the build backend to use in the generated pyproject.toml file. By default, the build backend is hatch (equivalent to --build-backend=hatch), but uv_build is also supported via --build-backend=uv.
• The usethis show sonarqube command is now considered ready for use. It now supports a --project-key option to specify the SonarQube project key, in addition to the previous method of using a dedicated tool.usethis.sonarqube.project-key configuration in pyproject.toml.
• Ruff rule hierarchies are now respected. For example, when "ALL" is selected, then other rules won't be explicitly added to the select list. Similarly, if "F" is ignored, then "F401" won't be explicitly ignored.

🐞 Bug Fixes

• Read-only operations on YAML files will no longer modify the file with cosmetic changes. There should also be a small performance improvement associated with avoiding unnecessary writes. It was incorrectly reported that this issue was fully resolved in v0.17.0, and the release notes have been retrospectively updated accordingly.

🦾 Robustness

• Submodules named _version.py in project packages will now be automatically excluded from the inferred Import Linter contracts, since these are often dynamically generated via tools such as setuptools_scm and hatch-vcs, and are not typical modules.
• The RUF059 Ruff rule (unused-unpacked-variable) is now ignored by default for the tests directory, since tests often include intentionally unused variables and the rule is overly strict in that context.

📚 Documentation

• The various usethis show commands are now explicitly documented in the README.

📦 Packaging

• The mergedeep dependency has been removed, since the package has been unmaintained since 2021.

🔧 Internal Changes

• Import cycles have now been broken through the is_likely_used heuristic function which provides the canonical heuristic for determining whether a tool is used based on its ToolSpec. A lack of import cycles is now enforced by both Import Linter and basedpyright.
• The config_spec method has been moved into ToolSpec to align more with the intention that ToolSpec corresponds to aspects of the tool specification which are unopinionated and are based on the inherent design of the tool (whereas the Tool subclass may involve various heuristics and opinionated decisions).
• The Tool class is now marked as @final to discourage subclassing. Likewise, ToolSpec methods are protected with @final to avoid inadvertently overriding its methods in the Tool subclass. Similarly, the @override decorator is explicitly used for methods which are providing an override implementation of an abstract method from the base class in Tool implementation subclasses.
• There is improved type compliance through the reduced use of typing.Any, especially for the KeyValueFileManager implementation. Some of this has been achieved through increased runtime validation with pydantic, which should improve the intelligibility of error messages when invalid data is encountered in configuration files such as pyproject.toml.
• UsethisFileManager has been renamed to FileManager with view to pull the file manager logic into a separate dependency in the future (see #1256). To the same end, the usethis._io module containing the FileManager and KeyValueFileManager definitions has been consolidated into the usethis._file module, as well as the print_keys function and the Key type alias.
• There is now a FileManager.revert() method to reduce the need to access private attributes. Various other internal methods have been renamed to promote them from private usage to better reflect their usage.
• FileManager and KeyValueFileManager are now explicitly marked as abstract base classes.
• All typer.Option objects now reside in a central module at usethis._ui.options. This helps bring consistency within modules and helps bring attention to potential duplication of options across modules to improve the overall consistency of the CLI.
• There is now a central usethis._fallback module for fallback versions of various packages. These provide the hard-coded values which are used when dynamic inference is not possible, such as when a backend such as uv is unavailable, or when populating pre-commit configuration.
• codecov and codspeed workflows no longer run for doc-only changes.
• There are now linters and formatters for markdown (enforced via prek). This is mostly to help facilitate the development and maintenance of agent skills.

What's Changed

• Bump actions/upload-artifact and actions/download-artifact by @nathanjmcdougall in #1426
• pkg._version should be added to exhaustive_ignores in Import Lint… by @nathanjmcdougall in #1427
• 1415 doc why doesnt usethis support automated setup of ci config by @nathanjmcdougall in #1428
• Move config_spec into ToolSpec by @Copilot in #1430
• Add @final to all methods in ToolSpec and Tool implementations by @Copilot in #1432
• Explain how to maintain docs in agent skills by @nathanjmcdougall in #1435
• Remove import cycles by @nathanjmcdougall in #1436
• Remove mergedeep dependency by @Copilot in #1437
• Use __getitem__ -> object instead of __getitem__ -> Any in FileManagers by @nathanjmcdougall in #1439
• enable reportMissingTypeStubs in basedpyright by @nathanjmcdougall in #1441
• enable reportInvalidAbstractMethod in basedpyright by @nathanjmcdougall in #1442
• Remove deprecated usethis ci from README and docs by @Copilot in #1445
• Reduce the use of typing.Any by @nathanjmcdougall in #1443
• Implement usethis tool ty and usethis typecheck by @nathanjmcdougall in #1446
• Improve the type annotation of empty container initializations by @nathanjmcdougall in #1447
• 1329 enable reportunannotatedclassattribute in basedpyright by @nathanjmcdougall in #1448
• Avoid branding of uv vs. uv in release notes/changelog by @Copilot in #1450
• Enable reportImplicitOverride in basedpyright by @nathanjmcdougall in #1449
• Update license badge to point to the GitHub license tab as a hyperlink by @nathanjmcdougall in #1452
• Consolidate usethis._io into usethis._file as new modules by @nathanjmcdougall in #1457
• Skip codecov and codspeed workflows for doc-only changes by @Copilot in #1456
• Implement usethis arch command by @Copilot in #1451
• [Breaking Change] Add usethis hook command and --hook/--no-hook to usethis init by @Copilot in #1454
• Enable reportPrivateUsage in basedpyright by @nathanjmcdougall in #1460
• Centralize CLI options/arguments arguments by @nathanjmcdougall in #1458
• Implement usethis badge ty by @Copilot in #1462
• Document usethis show subcommands in CLI overview page by @Copilot in #1461
• Set acyclic siblings contract for development by @nathanjmcdougall in #1470
• Add tests for Ruff dev deps not removed when using pre-commit by @Copilot in #1464
• Add a ...

🚧 Deprecations

• The usethis ci bitbucket command, and the usethis ci command in general, are deprecated. Their removal is planned for usethis 0.20.0. For feedback and discussion, please see #1313.

🐞 Bug Fixes

• Previously, parsing of pyproject.toml would fail on some Unicode characters. This has been fixed by specifying the encoding explicitly.

🧹 Maintenance

• The latest version of the Bitbucket Pipelines configuration file schema is now supported, specifically source import pipelines (in addition to the legacy inline import pipelines).

📚 Documentation

• There is now documentation on how to add a new tool to usethis in CONTRIBUTING.md.
• There is now clearer guidance in CONTRIBUTING.md regarding the use of docstrings in the test suite.
• The Scientific Python Library Development Guide is now mentioned in the README.

🔧 Internal Changes

• A bug in the pipeweld utility has been fixed. The bug did not functionally affect usethis, but involved incorrect insertion behaviour of Parallel components in the presence of empty Series branches.
• As of uv version 0.9.9, uv supports the UV_NO_DEFAULT_GROUPS environment variable, which is now being used for CI configuration. This causes changes to tested behaviour of usethis, and so the lowest tested version of uv is now v0.9.9. Going forward, it is not recommended to use older versions of uv with usethis.
• There are now various agent skills configured for agentic development.
• There is now explicit environment configuration for the GitHub Copilot agent.
• There are now separate GitHub Actions workflows for static checks, pytest, codspeed, and codecov analysis. This helps reduce the scope of permissions to repo secrets and generally simplifies things.
• There is now a GitHub Actions workflow for manually triggering a version bump to a specific package (for development). This is mostly to improve the maintenance experience for addressing CVEs.
• The Tool class now inherits from ToolSpec for the methods which do not involve dynamic inference.
• Many methods on the Tool and ToolSpec classes have been renamed and reorganized for convenience, including the introduction of a ToolMeta abstraction for grouping basic tool metadata (name, documentation URL, etc.).
• There is now a dedicated module for heuristics for detecting tool usage.
• The logic for selecting CI vs. pre-commit is now abstracted into the Tool class instead of being repeated for individual tool implementations.
• Various submodules of usethis._integrations have been promoted into their own higher level modules to accommodate these changes while preserving a layered architecture.
• There are various improvements in type compliance via the enabling of various basedpyright rules which were previously disabled.

What's Changed

• Major architecture changes to improve CI vs. pre-commit selection logic by @nathanjmcdougall in #1286
• Fix structure of logic to determine whether to add new bitbucket steps by @nathanjmcdougall in #1296
• Bump Bitbucket schema .py file by @nathanjmcdougall in #1299
• Remove redundant basedpyright config by @nathanjmcdougall in #1301
• Give clearer guidance regarding the use of docstrings in the test suite by @nathanjmcdougall in #1302
• Enable reportArgumentType in basedpyright by @nathanjmcdougall in #1305
• Enable reportPrivateLocalImportUsage in basedpyright by @nathanjmcdougall in #1309
• Enable reportAttributeAccessIssue in basedpyright by @nathanjmcdougall in #1307
• Remove TYPE_CHECKING protected import cycles by @nathanjmcdougall in #1314
• Clarify intent of Tool.name in docstring by @nathanjmcdougall in #1317
• Document how to add a new tool by @nathanjmcdougall in #1318
• Introduce ToolSpec and ToolMeta abstractions to keep tool classes more accessible by @nathanjmcdougall in #1342
• Bump markdown as a dev dep by @nathanjmcdougall in #1344
• Specify an environment for CI Actions config by @nathanjmcdougall in #1347
• Bump zizmor to v0.5.2 by @nathanjmcdougall in #1349
• Refactor Tool defaults into standalone ToolSpec methods and is_likely_used function by @Copilot in #1351
• Switch to CodSpeed simulation mode by @nathanjmcdougall in #1354
• Move to agent skills and AGENTS.md by @nathanjmcdougall in #1355
• 1362 create import linter skill by @nathanjmcdougall in #1364
• Add an agent skill to modify the Python module layout by @nathanjmcdougall in #1365
• Give contract strategy for usethis-qa-import-linter by @nathanjmcdougall in #1370
• Give a strategy for broken references in `usethis-python-module-layou… by @nathanjmcdougall in #1372
• Add a github-actions-update skill by @nathanjmcdougall in #1374
• Skip CI for .md file changes in .agents dir by @Copilot in #1367
• Forbid functools.singledispatch / singledispatchmethod via Ruff banned-api by @Copilot in #1361
• Disable basedpyright rule reportUnusedFunction only for tests by @nathanjmcdougall in #1375
• Explain the need to update the test directory structure in `usethis-p… by @nathanjmcdougall in #1379
• 1380 configure agent dev env by @nathanjmcdougall in #1383
• Split usethis._tool.impl into impl/spec and impl/base submodules by @Copilot in #1373
• Add a skill for modifying Python code by @nathanjmcdougall in #1384
• Mention uv run pytest tests\test_suite.py::test_skeleton_matches fo… by @nathanjmcdougall in #1387
• Explicitly activate the venv for copilot agent setup by @nathanjmcdougall in #1386
• Enable reportUnreachable in basedpyright by @Copilot in #1376
• Bump the minimum supported version of uv to 0.9.9 by @nathanjmcdougall in #1390
• Add a GitHub Actions workflow for bumping dev deps with manual trigger by @nathanjmcdougall in #1394
• Add PR-generating capabilities to the bump-dev-dep workflow by @nathanjmcdougall in #1396
• Enable reportUnnecessaryTypeIgnoreComment in basedpyright by @nathanjmcdougall in #1395
• Allow a failing uv-export run (means update has occurred) by @nathanjmcdougall in #1397
• Set git user config to use github-actions[bot] by @nathanjmcdougall in #1400
• Enable reportUnnecessaryComparison in basedpyright by @Copilot in #1399
• Set PREK_UV_SOURCE: github for prek in static checks GitHub action by @nathanjmcdougall in #1402
• Remove unnecesssary manual commit step in `.github\workflows\bump-dev… by @nathanjmcdougall in #1404
• Actions/fix commit permissions by @nathanjmcdougall in #1405
• Exclude AGENTS.md from triggering CI by @Copilot in #1409
• Clean up cosmetics on dev dep bumping by @nathanjmcdougall in #1411
• Explicitly instruct agents to use particular skills in AGENTS.md by @nathanjmcdougall in #1407
• Bump black to 26.3.1 in dev lockfile by @nathanjmcdougall in #1393
• Enable reportUnknownParameterType in basedpyright by @Copilot in #1403
• Mention sp-repo-review in the README by @nathanjmcdougall in #1418
• Enable reportUnusedParameter in basedpyright by @Copilot in #1414
• Deprecate usethis ci in v0.19.0 ahead of removal in v0.20.0 by @Copilot in #1416
• Fix a bug in pipeweld for inserti...

🐞 Bug Fixes

• usethis show commands will no longer hard-wrap outputs, which gave invalid results in some cases, e.g. when running usethis show sonarqube with long sonar.projectKey fields.

🦾 Robustness

• Fallback icons (e.g. √, □, i, ×, !) for message icons (✔, ☐, ℹ, ✗, ⚠) are now used for terminals which don't support unicode.
• Identical warnings will now never display twice for the same command.
• When a backend is not being used, the inferred version of Python based on the current interpreter is now compared with the requires-python bounds from pyproject.toml. If there is a mismatch, a warning is now emitted.
• The tomli dependency on codespell is only declared as a dependency for Python versions 3.10 and below, since for versions 3.11 onwards, codespell uses tomllib from the standard library. This is based on the requires-python bounds from pyproject.toml if available, otherwise by the current interpreter.

📦 Packaging

• As per the notes for 0.16.0, Version 0.18.13 of ruamel.yaml introduced a regression relating to indentation. The new versions 0.19.0 and 0.19.1 of ruamel.yaml are now also excluded as dependency versions until this is addressed in a future release.

🔧 Internal Changes

• Rule management logic is now abstracted into the Tool class, reducing duplication between the logic used for deptry and Ruff.
• Import Linter contracts for development have been moved from pyproject.toml to .importlinter for tidiness.

What's Changed

• Use schema namespaces instead of messy lists of imported classes by @nathanjmcdougall in #1267
• Move tool management methods into Tool to reduce duplication by @nathanjmcdougall in #1268
• Tweak grammar in SECURITY.md by @nathanjmcdougall in #1269
• Exclude ruamel.yaml v0.19.0 and v0.19.1 due to regression by @nathanjmcdougall in #1274
• Add caching to warn_print by @nathanjmcdougall in #1276
• 1183 respect requires python bounds in get supported major python versions for none backend by @nathanjmcdougall in #1273
• Move Import Linter config to .importlinter to reduce clutter by @nathanjmcdougall in #1279
• Conditionally include tomli as a codespell dep based on Python version by @nathanjmcdougall in #1277
• Use fallback icon sets for terminals that don't support unicode by @nathanjmcdougall in #1278
• Refactor get_required_minor_python_versions for clarity by @nathanjmcdougall in #1280
• Bump urllib3 by @nathanjmcdougall in #1281
• Enable soft wrapping for plain_print by @nathanjmcdougall in #1288
• Add changelog for 0.18.1 by @nathanjmcdougall in #1290

Full Changelog: v0.18.0...v0.18.1

💥 Changes

• Previously, when available, uv would be used as a package manager backend when pyproject.toml existed, even if there was no lockfile. This was considered to have too many false positives for projects using different systems (e.g. setup.py with linter configuration in pyproject.toml). Now, in lieu of any other evidence such as [tool.uv] sections in pyproject.toml, the default is to use the --backend=none behaviour.
• Previously, tools configured via pre-commit would not be declared as dev dependencies unless necessary, namely the tools codespell and pyproject-fmt. Now, they are always declared as dev dependencies (when using the uv package manager backend).

🚀 New Features

• Import Linter contract inference via usethis tool import-linter now supports namespace packages.
• The new .coveragerc.toml file introduced by Coverage.py in v7.13.0 is now supported by usethis.
• The new pre-commit language alias of unsupported instead of system introduced in v4.4.0 is now used when the minimum version of pre-commit is declared via minimum_pre_commit_version at 4.4.0 or greater.
• The default Coverage.py configuration now sets relative_files = true to use relative paths e.g. in XML coverage reports. This helps improve robustness when parsing coverage reports as artifacts between CI jobs.
• By default, usethis will now explicitly include dev dependencies in requirements.txt export configuration when using usethis tool requirements.txt. Previously this was implicit via the editable install -e . declaration.
• There is now a usethis show backend command which emits the inferred backend (currently; one of uv or none).

🐞 Bug Fixes

• There are no longer fatal crashes while running usethis tool import-linter in the presence of empty directories in the source directory.
• Root-level .py files (e.g. setup.py) are no longer considered packages for Import Linter contract inference when using usethis tool import-linter.

🦾 Robustness

• A speedup of up to 30% has been achieved in some situations by using atomic writes (and reducing duplicated reads) for YAML files.
• When using the uv backend, if pyproject.toml does not yet exist, it will not be created unnecessarily when running usethis tool requirements.txt.
• Test directory-related ignores for Ruff config (i.e. referencing tests/**) are now only generated when the tests directory actually exists.
• PT-code Ruff rules (relating to pytest) are explicitly ignored for non-tests directories.
• Error messages for subprocess failures now emit the failing command for better diagnosability.
• Subprocess failures for uv no longer emit the full pyproject.toml contents.

🧹 Maintenance

• The latest version of the Bitbucket Pipelines configuration file schema is now supported, specifically support for new options available regarding pipeline triggers and self-hosted runners.

📚 Documentation

• There is now dedicated guidance on the docs site for using usethis together with popular frameworks like Django, FastAPI, and Dagster.
• A detailed example of usethis init has been pulled out the README into a dedicated docs page.
• The license is now documented on the docs site (in addition to the LICENSE file).
• Branding (colours, project naming) etc. is now documented in CONTRIBUTING.md.
• There is now a favicon on the docs site.
• There are now dedicated 404 pages for the docs site.
• The correct URL is now used for the pyproject-fmt homepage.

📦 Packaging

• As per the notes for 0.16.0, Version 0.18.13 of ruamel.yaml introduced a regression relating to indentation. The new version 0.18.17 of ruamel.yaml is now also excluded as a dependency version until this is addressed in a future release.

🔧 Internal Changes

• As of uv version 0.8.18, uv now allows pyproject.toml to be missing [project] sections. This causes changes to tested behaviour of usethis, and so the lowest tested version of uv is now v0.8.18. Going forward, it is not recommended to use older versions of uv with usethis.
• The GitHub Actions for publishing to PyPI now use separate build and publish steps to reduce the scope of publish token permissions.
• CI pipelines are now triggered for all changes, including documentation-only changes, since documentation includes tested codeblocks.
• Codspeed runners in CI now run on Python 3.13 to reduce duplication between Python 3.14 runners.
• The config for prek now uses the priority option to enable concurrency between hooks.
• The pyright-style type checker has been migrated from pyright to a similar alternative, basedpyright.

What's Changed

• Split build and publish environments for PyPI releases via GitHub Act… by @nathanjmcdougall in #1137
• Add trigger configuration support to Bitbucket pipelines config by @nathanjmcdougall in #1140
• Rework docs to add new detailed example section by @nathanjmcdougall in #1141
• Add missing uv setup step in release.yml by @nathanjmcdougall in #1145
• Enable strict built-in shadowing checks in Ruff by @nathanjmcdougall in #1146
• No longer exclude default groups (e.g. dev dependencies) when generat… by @nathanjmcdougall in #1147
• Add favicon by @nathanjmcdougall in #1156
• Bump mkdocs-material to fix 404 pages by @nathanjmcdougall in #1157
• Add get_uv_version function by @nathanjmcdougall in #1158
• Include license in the docs by @nathanjmcdougall in #1159
• Add a section describing how to use usethis with other frameworks lik… by @nathanjmcdougall in #1160
• Implement a get_minimum_pre_commit_version function by @nathanjmcdougall in #1165
• Bump bitbucket pipelines schema to include self-hosted config by @nathanjmcdougall in #1179
• Bump urllib3 by @nathanjmcdougall in #1178
• Support base-level namespace packages in usethis tool import-linter… by @nathanjmcdougall in #1182
• Don't infer uv is used if there's no lockfile but pyproject.toml a… by @nathanjmcdougall in #1163
• Forbid ruamel-yaml 0.18.17 by @nathanjmcdougall in #1191
• Clarify docstring in use_ruff by @nathanjmcdougall in #1189
• Rewording README regarding roadmap timeframes by @nathanjmcdougall in #1196
• Refactor Python version logic into a dedicated class by @nathanjmcdougall in #1216
• Don't output pyproject.toml contents in uv subprocess fail error … by @nathanjmcdougall in #1217
• Trigger CI on doc-only changes by @nathanjmcdougall in #1219
• Add support for .coveragerc.toml by @nathanjmcdougall in #1222
• Move codspeed to 3.13 in CI to avoid duplicating runs with 3.14 by @nathanjmcdougall in #1223
• Use correct URL for pyproject-fmt homepage by @nathanjmcdougall in #1224
• Fix case of empty package directory under usethis tool import-linter by @nathanjmcdougall in #1227
• Ignore root-level .py files for Import Linter inference by @nathanjmcdougall in #1228
• Use consistent naming for "Dot" Config Managers by @nathanjmcdougall in #1229
• Ensure test directory ignore rules are only added if the /tests exists by @nathanjmcdougall in #1232
• Use relative paths in Coverage.py configuration by @nathanjmcdougall in #1235
• Add support for new unsupported and unsupported_script languages … by @nathanjmcdougall in #1238
• Create a get_pre_commit_version function by @nathanjmcdougall in #1240
• Migrate the pre-commit and bitbucket YAML integrations to use FileManagers by @nathanjmcdougall in #1247
• Use adaptive logic to decide on correct alias for pre-commit system/u… by @nathanjmcdougall in #1241
• Properly introduce test-related rule config when adding pytest by @nathanjmcdougall in #1249
• Document in the copilot-instructions.md that .gitignore should never … by @nathanjmcdougall in https://github.com/usethis-python/usethis-p...

🚀 New Features

• The usethis ci bitbucket command will now automatically use parallelism between pipeline steps where possible.
• The usethis ci bitbucket command now has a --no-matrix-python option to opt-out of generating a Python version matrix for CI pipelines, i.e. to only test against a single Python version.
• The behaviour of --backend=none is now the default when Poetry is detected, and a warning is displayed. This would change in a future release when a Poetry backend is implemented.
• The command usethis badge socket has been added, which adds a Socket badge to the README for your PyPI package, giving a security scan rating.

🐞 Bug Fixes

• usethis tool import-linter will no longer add INP rules multiple times when run repeatedly.
• The (undocumented) usethis show sonarqube command previously gave invalid config for flat directory structures; this has been fixed. Also, the command no longer creates a pyproject.toml file if it does not already exist.
• When running usethis tool requirements.txt with --backend=none, the how-to-use message misleadingly implies that a pre-existing requirements.txt file would be modified; this message no longer displays in this case.
• Read-only operations on YAML files will no longer modify the file with cosmetic changes in some cases. A full fix will be included in a future release.

🦾 Robustness

• Unrecognized entries (i.e. not found in the JSON Schema Store) in .pre-commit-config.yaml and bitbucket-pipelines.yml files will no longer cause validation errors or be dropped. Other minor improvements to the schema validation logic have also been made to improve robustness when roundtripping files.
• The usethis ci bitbucket command will add the pre-commit cache to pre-commit steps when using the --backend=none behaviour.
• Running usethis init with --backend=none will now explicitly instruct the user about any dependencies that need to be managed manually.
• References to Bitbucket Pipelines are now consistently capitalized and pluralized throughout the codebase.

📚 Documentation

• The FAQ now explicitly explains whether uv is necessary to use usethis, and gives some guidance for Poetry users.
• Instructions for implementing a new usethis badge command in usethis have been added to the CONTRIBUTING.md file.
• Some instructions for how to diagnose slow pytest collection speeds are now in CONTRIBUTING.md.
• There is now an acknowledgements section in the README.
• The CONTRIBUTING.md file now explains how to run the CLI from within a temporary project directory.
• The CONTRIBUTING.md file explicitly mentions that type annotations should not be included in docstrings.
• The CONTRIBUTING.md file now explains the details of the usethis._config.usethis_config global state object.
• All usethis tool commands are now explicitly enumerated in the README.
• The README now explicitly links to the ReadTheDocs site.
• The CLI Reference had issues with indentation of sub-bullet points; this has been resolved.
• A few badges have been moved and added to the Development section of the README.

📦 Packaging

• As per the notes for 0.16.0, Version 0.18.13 of ruamel.yaml introduced a regression relating to indentation. The new version 0.18.16 of ruamel.yaml is now also excluded as a dependency version until this is addressed in a future release.

🔧 Internal Changes

• There is now a method Tool.default_command() to specify any CLI command associated with a tool, to reduce duplication across the codebase.
• The ty type checker from Astral has been added, and now runs via pre-commit hooks. Pyright continues to be used in the CI, but not via pre-commit.
• The zizmor CI runner no longer triggers for documentation-only changes.
• There is now a copilot-instructions.md file to configure GitHub Copilot.
• The test to ensure the docs stay synchronized with the README has been weakened and no longer hard-codes any content from the README. This should reduce the flakiness of this test for README-only changes.

What's Changed

• Move badges down the README.md (#1030) by @nathanjmcdougall in #1031
• Forbid ruamel.yaml v0.18.16 and update README test to pass CI by @nathanjmcdougall in #1040
• Don't duplicate ignored rules matching glob by @nathanjmcdougall in #1042
• Fix print-how-to-use for requirements.txt with none backend by @nathanjmcdougall in #1043
• Add Ruff badge to development section of the README by @nathanjmcdougall in #1046
• Don't create pyproject.toml if it does not exist when showing SonarQu… by @nathanjmcdougall in #1048
• Add a read-only context manager for YAML files to prevent round-trip … by @nathanjmcdougall in #1047
• 1027 omissions in messages for usethis init backend=none by @nathanjmcdougall in #1049
• Explicitly document the ruamel.yaml dependency constraints in the 0… by @nathanjmcdougall in #1052
• Allow extra fields in YAML schema modules, add stricter validation by @nathanjmcdougall in #1050
• Add some documentation about whether uv is necessary by @nathanjmcdougall in #1054
• Add some instructions for diagnosing slow test collection speeds by @nathanjmcdougall in #1055
• Fix sub-bullet point markdown formatting in CLI reference by @nathanjmcdougall in #1057
• Ignore doc-only changes when triggering zizmor scanning by @nathanjmcdougall in #1056
• Explicitly link to the ReadTheDocs site from the README by @nathanjmcdougall in #1058
• Add explicit guidance for poetry users in FAQ by @nathanjmcdougall in #1060
• Support parallel step insertion and parallelism breakup in Bitbucket pipelines by @Copilot in #1051
• Add support for detecting poetry projects automatically and using the… by @nathanjmcdougall in #1059
• Explicitly mention all usethis tool interfaces in the README by @nathanjmcdougall in #1061
• Use consistent capitalization of bitbucket pipelines by @nathanjmcdougall in #1067
• Fix whitespace and grammar by @nathanjmcdougall in #1068
• Add acknowledgements section by @nathanjmcdougall in #1066
• Fix pluralization of *_bitbucket_pipelines_config functions by @nathanjmcdougall in #1072
• Refactor the src\usethis\_core\ci.py module by @nathanjmcdougall in #1073
• Fix Bitbucket pipelines capitalization/pluralization in docstrings by @nathanjmcdougall in #1074
• Weaken the README sync test to reduce content duplication by @nathanjmcdougall in #1083
• Tweak wording in README by @nathanjmcdougall in #1076
• Document how to add new badge implementations by @nathanjmcdougall in #1081
• 1063 usethis badge socket by @nathanjmcdougall in #1080
• Add CLI-level test for import pipeline error handling in Bitbucket integration by @Copilot in #1085
• Add copilot instructions file, improve CONTRIBUTING.md detail. by @nathanjmcdougall in #1087
• Migrate to Ruff 0.14.3 by @nathanjmcdougall in #1094
• Document test side-effect prevention guidelines by @Copilot in #1096
• Document usethis_config global state management by @Copilot in #1100
• Add Tool.default_command() to eliminate duplication in CI steps and help messages by @Copilot in #1088
• Fix SonarQube double indexing in flat layout by excluding tests from sources by @Copilot in #1091
• Disable PLR0913 in the interface layer by @nathanjmcdougall in #1105
• Add --matrix-python/--no-matrix-python flag to opt out of CI matrices by @Copilot in #1089
• Add helper methods to get_sonar_project_properties by @nathanjmcdougall in #1107
• json.schemastore.org -> www.schemastore.org by @nathanjmcdougall in #1109
• Add pre-commit cache to Bitbucket pipeline step for pre-commit for … by @nathanjmcdougall in https://github.com/usethis-python/...

0.16.0

🚀 New Features

• Most commands now accept a --backend option to specify the package manager backend to use. Up to this point, uv was the only supported backend. Now, a --backend=none option is available to use usethis without uv. This is a step toward supporting other backends such as Poetry in the future. When unspecified, heuristics will be used to determine the backend.
• The use of pyproject.toml in a project is no longer assumed or imposed on a project when not using the uv backend.
• pre-commit configurations are now more conventional, preferring URL-based repo configuration instead of local repos with language: system. The previous behaviour was designed to ensure synchronization of versions between the uv lockfile and the pre-commit configuration, but this is now provided by the sync-with-uv pre-commit hook, which is added automatically when using pre-commit with uv.
• When using usethis author, a message with the author's name is now outputted in the console.

🦾 Robustness

• Pydantic warnings relating to deprecated access to the model_fields attribute on an instance should no longer occur.
• The tool.deptry.ignore_notebooks configuration for deptry is set explicitly to the default value of false to hint that deptry is being used, and to hint on how to configure it.

🐞 Bug Fixes

• Previously, the usethis ci bitbucket command would fail to add Import Linter configuration to the CI pipeline when import-linter was detected. This has been fixed.
• The usethis badge pypi command would generate markdown with invalid syntax due to a stray < character. This has been fixed.

🧹 Maintenance

• The default version of pyproject-fmt when used as a pre-commit has been bumped from v2.6.0 to v2.11.0.
• The latest version of the Bitbucket Pipelines configuration file schema is now supported, specifically inline and custom pipeline step types; the input_variables configuration for steps, and the new name scoped for the artifacts upload type option unshared.

📚 Documentation

• Hyperlinks in the README and CONTRIBUTING.md files now point to the stable documentation site (rather than the latest site).
• The configurator project is now documented as a similar project in the README.

📦 Packaging

• Python 3.14 is now formally supported.
• click is no longer a direct dependency.
• Version 0.18.13 of ruamel.yaml introduced a regression relating to indentation. This version, along with 0.18.14 and 0.18.15, are now excluded as dependency versions to avoid this issue until it is addressed in a future release.

🔧 Internal Changes

• The CI configuration has been overhauled. uv is used in more conventional ways. A runner has been added for bleeding edge dependency versions. The CI now runs on a cron schedule. zizmor has been added for security scanning. Permissions are more tightly scoped and explained. All actions have been bumped to their latest versions.
• The pre-commit hooks have been migrated to use prek rather than pre-commit for development.
• pytest-sugar has been added for a more user-friendly test suite output, and pytest-emoji has been removed.

What's Changed

• Fix typo in docstring of Tool.get_install_method by @nathanjmcdougall in #917
• Change hyperlinks to point to stable docs by @nathanjmcdougall in #918
• Bump bitbucket pipelines schema by @nathanjmcdougall in #926
• Remove stray brace in get_pypi_badge by @nathanjmcdougall in #925
• Display a message when setting an author with add_author by @nathanjmcdougall in #927
• Include error handling when trying to set UTF-8 outputs by @nathanjmcdougall in #928
• Add --backend flag to over-ride manual detection of uv by @nathanjmcdougall in #826
• Update codecov badge token by @nathanjmcdougall in #931
• Bump Bitbucket pipelines schema to support custom steps and both inli… by @nathanjmcdougall in #940
• Only use pyproject.toml for config when it already exists by @nathanjmcdougall in #934
• Bump pyproject-fmt to v2.7.0 by @nathanjmcdougall in #955
• Add support for the input-variables step field in BitBucket pipelines by @nathanjmcdougall in #956
• Pass CI on uv 0.9.0 (Python 3.14) by @nathanjmcdougall in #961
• Avoid accessing model_fields on an instance in fancy_model_dump and… by @nathanjmcdougall in #964
• Declare Python 3.14 support by @nathanjmcdougall in #959
• Use uv sync to set up dependencies in ci.yaml by @nathanjmcdougall in #876
• Add CI runner for bleeding edge versions, refactor matrix configuration by @nathanjmcdougall in #965
• Migrate from pre-commit to prek by @nathanjmcdougall in #969
• Comply with zizmor by @nathanjmcdougall in #971
• Add pytest-sugar for dev by @nathanjmcdougall in #974
• Configure cron schedule for CI by @nathanjmcdougall in #975
• Add sync-with-uv and use more conventional pre-commit config by @nathanjmcdougall in #978
• Ensure Import Linter is added via use_ci_bitbucket by @nathanjmcdougall in #988
• Enable max-deps CI worker on PRs by @nathanjmcdougall in #993
• Document configurator as a similar project by @nathanjmcdougall in #998
• Bump GitHub action versions by @nathanjmcdougall in #996
• Set [tool.deptry.ignore_notebooks] explicitly as deptry config by @nathanjmcdougall in #989
• 909 make bitbucket ci config backend agnostic by @nathanjmcdougall in #953
• Use python-version in setup-uv GitHub action and Consolidate CI steps by @nathanjmcdougall in #999
• Remove pytest-emoji by @nathanjmcdougall in #1001
• Add sync-with-uv for repos using pre-commit with uv by @nathanjmcdougall in #1005
• Broaden exception handling in test_matches_schema_store tests by @nathanjmcdougall in #1009
• Add zizmor GitHub actions config by @nathanjmcdougall in #1007
• Remove unnecessary contents: read permissions by @nathanjmcdougall in #1019
• Move to standard pre-commit configuration where possible by @nathanjmcdougall in #1017
• 502 if uv isnt used dont add a pre commit config relying on uv by @nathanjmcdougall in #1023
• Add changelog for v0.16.0 by @nathanjmcdougall in #1025

Full Changelog: v0.15.2...v0.16.0

🦾 Robustness

• Previously, empty .pre-commit-config.yaml files would cause errors, (since they are not considered valid by pre-commit). Now usethis will treat them as if they do not exist, and so will write new config to them if applicable, rather than raising a validation error for this case.

🐞 Bug Fixes

• When subprocessing uv, the usethis init command will no longer use the default for --build-backend, and instead will always explicitly use hatch. This may change in the future if the default supported build backend for usethis becomes uv_build, which is the new default for uv v0.8.0. This change avoids creating broken config which mixes uv_build with hatch config.
• When adding Import Linter while using Ruff, the INP rules are selected, but ignored for the tests directory. However, no message would be displayed in cases where those rules were already selected but not already ignored. Now, a message will be displayed in this case.

📚 Documentation

• A documentation site is now available at https://usethis.readthedocs.io/en/stable/. The CLI Reference section has been moved there from the README. Other minor wording and clarity improvements have been made.
• The CLI reference now mentions that usethis tool pre-commit will install hooks to Git.

🔧 Internal Changes

• The doc dependency group is no longer a default group. This reduces the dependencies required on CI.

What's Changed

• Reword changelog for v0.15.1 by @nathanjmcdougall in #873
• Rename ensure_file_manager_exists to ensure_managed_file_exists by @nathanjmcdougall in #872
• Use uv sync to set up dependencies in ci.yaml by @nathanjmcdougall in #874
• Revert "Use uv sync to set up dependencies in ci.yaml" by @nathanjmcdougall in #875
• Remove nested parenthesis in README by @nathanjmcdougall in #877
• Reword description of usethis ci to clarify there is no recommended… by @nathanjmcdougall in #878
• Mention that usethis test includes Coverage.py by @nathanjmcdougall in #879
• Remove idempotent encode-decode calls for unicode character by @nathanjmcdougall in #882
• 881 usethis tool import linter doesnt give message for ignoring inp by @nathanjmcdougall in #885
• Configure some tests to run offline by @nathanjmcdougall in #890
• Don't use doc group in testing CI by @nathanjmcdougall in #896
• Mention that usethis tool pre-commit will install hooks in the docs by @nathanjmcdougall in #899
• Break the README into docs pages, remove the CLI ref from the README by @nathanjmcdougall in #898
• Always use --build-backend hatch for uv init subprocesses from `u… by @nathanjmcdougall in #901
• Update faq.md for grammar by @nathanjmcdougall in #903
• Support empty .pre-commit-config.yaml files by @nathanjmcdougall in #906
• Add changelog for v0.15.2 by @nathanjmcdougall in #914

Full Changelog: v0.15.1...v0.15.2

🐞 Bug Fixes

• Previously, when using Import Linter with Ruff, the INP rule would be ignored in the tests directory via an incorrect glob pattern of "*/tests/**"; this has been fixed to "tests/**".
• A TOML integration problem could cause broken configuration in some cases. This could occur on deeply nested keys, such as the per-file-ignores for Ruff directories in pyproject.toml when using Import Linter. This has now been fixed.

📚 Documentation

• Some issues with mismatched bullet points in the CLI docs section of the README have been addressed.
• The opening paragraph of the README has been reworded for clarity, and various other minor changes have been made.

🔧 Internal Changes

• Changes to the CI and the test suite have been made to support uv v0.8.0. Newer features of uv are now required in the CI configuration, meaning the lowest tested version of uv is now v0.6.8. Going forward, it is not recommended to use older versions of uv with usethis.

What's Changed

• Fix mismatched bullet points in README.md by @nathanjmcdougall in #858
• Fix bullet-point mismatch in README by @nathanjmcdougall in #857
• Clarify opening paragraph in README by @nathanjmcdougall in #859
• Grammar in Manage the README vs. Manage README by @nathanjmcdougall in #860
• Implement Dependency.to_requirements_string by @nathanjmcdougall in #861
• For Import Linter, Fix INP config glob pattern, add its config when a… by @nathanjmcdougall in #864
• Support uv v0.8.0 by @nathanjmcdougall in #867
• Update guidance on checking uv version to reflect change to `uv sel… by @nathanjmcdougall in #868
• Don't break Ruff TOML config when adding Import Linter by @nathanjmcdougall in #865
• Add changelog for v0.15.1 by @nathanjmcdougall in #871

Full Changelog: v0.15.0...v0.15.1

🚀 New Features

• The usethis tool mkdocs command has been implemented to manage MkDocs documentation sites. Also, the higher-level usethis doc command has been added, which has the same effect.
• The --doc option for usethis init has been implemented to initialize MkDocs documentation sites by default. The old behaviour can be restored by passing --no-doc.
• Coverage.py for measuring test coverage is now included by default when using usethis test or usethis init with the default --test option. This provides out-of-the-box test coverage reporting.
• The --frozen option is now supported in the usethis ci and usethis docstyle commands. Similar to other commands, this will leave the virtual environment and lockfile unchanged.
• The --offline option is now supported in the usethis docstyle command. This will run the command without network access.

🦾 Robustness

• Incorrectly structured TOML files will emit better messages and in some cases will be handled gracefully, specifically in cases where a non-mapping value is encountered where a mapping is expected.

📦 Packaging

• Bounds are now placed on the build dependencies for usethis (i.e. hatch-vcs>=0.5.0,<0.6.0 and hatchling>=1.27.0,<1.28.0), which should improve reproducibility of builds in the long run.

🔧 Internal Changes

• A YAMLFileManager has been implemented to manage YAML files, which is used for the MkDocs configuration file mkdocs.yml.
• A new get_project_deps method has been added to retrieve core project dependencies from the pyproject.toml file, specifically from the project.dependencies section. This will be used in a future release to support non-uv based backends, such as Poetry.

What's Changed

• Set bounds on build requirements by @nathanjmcdougall in #841
• Include Coverage.py as a default recommended test framework tool as a… by @nathanjmcdougall in #835
• 837 handle unexpected non mappings better in toml files by @nathanjmcdougall in #840
• 827 implement a yamlfilemanager by @nathanjmcdougall in #833
• Support --frozen in usethis ci by @nathanjmcdougall in #845
• Support --offline and --frozen in usethis docstyle by @nathanjmcdougall in #846
• Bump pyright from v1.1.399 -> v1.1.403 by @nathanjmcdougall in #848
• Implement get_project_deps and tests by @nathanjmcdougall in #853
• Update ConfigEntry docstring to sync with attributes by @nathanjmcdougall in #852
• Implement usethis tool mkdocs by @nathanjmcdougall in #823
• Implement usethis doc and usethis init --doc by @nathanjmcdougall in #854
• Changelog/0.15.0 by @nathanjmcdougall in #855

Full Changelog: v0.14.2...v0.15.0