Update docs as pre-release for 1.17.0 (#2287)

* Update docs as pre-release for 1.17.0

* Add blog post

* Update blog post

Author: cjames23

docs/blog/posts/release-hatch-1170.md

@@ -0,0 +1,140 @@
+---
+date: 2026-05-30
+authors: [cjames23]
+description: >-
+  Hatch v1.17.0 brings lockfile support and a new unified check command.
+categories:
+  - Release
+---
+
+# Hatch v1.17.0
+
+Hatch [v1.17.0](https://github.com/pypa/hatch/releases/tag/hatch-v1.17.0) brings first-class lockfile support and a new `hatch check` command that unifies code quality checks under a single, extensible interface.
+
+<!-- more -->
+
+## Lockfile support
+
+ Hatch now generates [PEP 751](https://peps.python.org/pep-0751/) lockfiles (`pylock.toml`) for your environments, capturing exact resolved versions and cryptographic hashes of every dependency.
+
+### Getting started
+
+Enable locking on any environment:
+
+```toml config-example
+[tool.hatch.envs.test]
+locked = true
+dependencies = [
+  "pytest",
+]
+```
+
+Or flip it on globally:
+
+```toml config-example
+[tool.hatch]
+lock-envs = true
+```
+
+Then generate lockfiles:
+
+```console
+$ hatch env lock
+Locking environment: default
+Wrote lockfile: pylock.toml
+Locking environment: test
+Wrote lockfile: pylock.test.toml
+```
+
+The `default` environment produces `pylock.toml`, while others follow the `pylock.<name>.toml` convention from PEP 751.
+
+### Automatic locking
+
+Environments configured with `locked = true` will have their lockfiles generated automatically during `hatch env create` or `hatch run` whenever the lockfile is missing or dependencies have changed. No extra steps required.
+
+### CI verification
+
+Use `--check` to verify lockfiles are up to date in CI pipelines:
+
+```console
+$ hatch env lock --check
+Lockfile is up to date: pylock.toml
+```
+
+This re-resolves dependencies and compares the result against the committed lockfile, failing if they diverge.
+
+### Upgrading dependencies
+
+Upgrade everything:
+
+```console
+$ hatch env lock --upgrade
+```
+
+Or target specific packages:
+
+```console
+$ hatch env lock --upgrade-package requests --upgrade-package urllib3
+```
+
+### Pluggable lockers
+
+The lockfile system is built on a plugin interface. Hatch ships two built-in lockers:
+
+- **UV** — uses `uv pip compile` with hash generation and `uv pip sync` for installation
+- **pip** — uses `pip lock` (requires pip 25.1+)
+
+The locker is selected automatically based on your environment's installer, or you can set it explicitly:
+
+```toml config-example
+[tool.hatch]
+locker = "uv"
+```
+
+Third-party locker plugins can be registered via the `hatch_register_locker` hook, implementing the `LockerInterface` to provide custom resolution strategies.
+
+### Additional commands
+
+- `hatch lock` — shorthand for locking the active environment
+- `hatch dep lock` — same workflow, scoped to the `-e` / `HATCH_ENV` selection
+- `hatch dep sync` — install from an existing lockfile (e.g. `uv pip sync`)
+- `--export` / `--export-all` — write lockfiles to custom paths or export all environments to a directory
+
+## The `hatch check` command
+
+The new [`check`](../../cli/reference.md#hatch-check) command brings linting, formatting verification, and type checking together under one roof:
+
+```console
+$ hatch check
+```
+
+That single invocation runs all three checks in sequence. You can also target individual checks:
+
+```console
+$ hatch check code    # static analysis (Ruff linter)
+$ hatch check fmt     # formatting verification (Ruff formatter)
+$ hatch check types   # type checking (Pyrefly)
+```
+
+Add `--fix` to automatically apply fixes for code and formatting issues:
+
+```console
+$ hatch check --fix
+```
+
+### Type checking with Pyrefly
+
+The `types` subcommand uses [Pyrefly](https://github.com/facebook/pyrefly) by default, bringing fast, incremental type checking to your workflow. It also supports `--cover` for type coverage reports and `--summarize` for error statistics.
+
+### Designed for extensibility
+
+The architecture behind `hatch check` is deliberately modular. Each subcommand (`code`, `fmt`, `types`) runs in its own dedicated managed environment (`hatch-check-code`, `hatch-check-fmt`, `hatch-check-types`), with its own scripts and configuration.
+
+This design sets the stage for extreme extensibility in future releases. The same pattern that lets Hatch manage Ruff and Pyrefly today will allow users to plug in their own checkers — security scanners, documentation linters, custom style enforcers, license auditors — as first-class `hatch check` subcommands. Each checker will be able to define its own environment, dependencies, and scripts, all orchestrated through the same unified interface.
+
+We are building toward a world where `hatch check` becomes the single entry point for every quality gate your project needs, with the plugin system handling the rest.
+
+
+### Support
+
+If you or your organization finds value in what Hatch provides, consider sponsoring our maintainers [Ofek](https://github.com/sponsors/ofek)[Cary](https://github.com/sponsors/cjames23) to assist with maintenance and more rapid development!

docs/community/contributing.md

@@ -48,17 +48,16 @@ hatch test --cover --all
 
 ## Lint
 
-Run automated formatting:
+Run automated formatting and linting fixes:
 
 ```bash
-hatch fmt
+hatch check --fix
 ```
 
-Run full linting and type checking:
+Run all checks (linting, formatting, type checking):
 
 ```bash
-hatch fmt --check
-hatch run types:check
+hatch check
 ```
 
 ## Docs

docs/config/environment/advanced.md

@@ -279,7 +279,7 @@ version = ["0.1.0", "0.2.0", "1.0.0"]
     ```toml config-example
     [tool.hatch.envs.test.overrides]
     matrix.foo.dependencies = [
-      "httpx",
+      "httpx2",
       { value = "cryptography" },
     ]
     ```

docs/config/internal/static-analysis.md

@@ -2,10 +2,13 @@
 
 -----
 
-Static analysis performed by the [`fmt`](../../cli/reference.md#hatch-fmt) command is ([by default](#customize-behavior)) backed entirely by [Ruff](https://github.com/astral-sh/ruff).
+Static analysis performed by the [`check code`](../../cli/reference.md#hatch-check-code) and [`check fmt`](../../cli/reference.md#hatch-check-fmt) commands is ([by default](#customize-behavior)) backed entirely by [Ruff](https://github.com/astral-sh/ruff).
 
 Hatch provides [default settings](#default-settings) that user configuration can [extend](#extending-config).
 
+!!! note
+    The [`fmt`](../../cli/reference.md#hatch-fmt) command is being deprecated. Use `hatch check code` for linting and `hatch check fmt` for formatting instead.
+
 ## Extending config
 
 When defining your configuration, be sure to use options that are prefixed by `extend-` such as [`extend-select`](https://docs.astral.sh/ruff/settings/#extend-select), for example:
@@ -73,10 +76,10 @@ Then instruct Ruff to consider your configuration as an extension of the default
     extend = "ruff_defaults.toml"
     ```
 
-Anytime you wish to update the defaults (such as when upgrading Hatch), you must run the [`fmt`](../../cli/reference.md#hatch-fmt) command once with the `--sync` flag e.g.:
+Anytime you wish to update the defaults (such as when upgrading Hatch), you must run the [`check code`](../../cli/reference.md#hatch-check-code) or [`check fmt`](../../cli/reference.md#hatch-check-fmt) command once with the `--sync` flag e.g.:
 
 ```
-hatch fmt --check --sync
+hatch check code --sync
 ```
 
 !!! tip
@@ -93,30 +96,43 @@ config-path = "none"
 
 ## Customize behavior
 
-You can fully alter the behavior of the environment used by the [`fmt`](../../cli/reference.md#hatch-fmt) command. See the [how-to](../../how-to/static-analysis/behavior.md) for a detailed example.
+You can fully alter the behavior of the environments used by the [`check code`](../../cli/reference.md#hatch-check-code) and [`check fmt`](../../cli/reference.md#hatch-check-fmt) commands. See the [how-to](../../how-to/static-analysis/behavior.md) for a detailed example.
+
+The `check code` command uses the `hatch-check-code` environment, and the `check fmt` command uses the `hatch-check-fmt` environment. The legacy `fmt` command continues to use the `hatch-static-analysis` environment.
 
 ### Dependencies
 
 Pin the particular version of Ruff by explicitly defining the environment [dependencies](../environment/overview.md#dependencies):
 
 ```toml config-example
-[tool.hatch.envs.hatch-static-analysis]
+[tool.hatch.envs.hatch-check-code]
+dependencies = ["ruff==X.Y.Z"]
+
+[tool.hatch.envs.hatch-check-fmt]
 dependencies = ["ruff==X.Y.Z"]
 ```
 
 ### Scripts
 
-If you want to change the default commands that are executed, you can override the [scripts](../environment/overview.md#scripts). The following four scripts must be defined:
+If you want to change the default commands that are executed, you can override the [scripts](../environment/overview.md#scripts).
+
+For the `hatch-check-code` environment:
 
 ```toml config-example
-[tool.hatch.envs.hatch-static-analysis.scripts]
-format-check = "..."
-format-fix = "..."
+[tool.hatch.envs.hatch-check-code.scripts]
 lint-check = "..."
 lint-fix = "..."
 ```
 
-The `format-*` scripts correspond to the `--formatter`/`-f` flag while the `lint-*` scripts correspond to the `--linter`/`-l` flag. The `*-fix` scripts run by default while the `*-check` scripts correspond to the `--check` flag.
+For the `hatch-check-fmt` environment:
+
+```toml config-example
+[tool.hatch.envs.hatch-check-fmt.scripts]
+format-check = "..."
+format-fix = "..."
+```
+
+The `*-fix` scripts run by default while the `*-check` scripts run when the `--fix` flag is not passed.
 
 !!! note "Reminder"
     If you choose to use different tools for static analysis, be sure to update the required [dependencies](#dependencies).
@@ -126,7 +142,10 @@ The `format-*` scripts correspond to the `--formatter`/`-f` flag while the `lint
 By default, [UV is enabled](../../how-to/environment/select-installer.md). You may disable that behavior as follows:
 
 ```toml config-example
-[tool.hatch.envs.hatch-static-analysis]
+[tool.hatch.envs.hatch-check-code]
+installer = "pip"
+
+[tool.hatch.envs.hatch-check-fmt]
 installer = "pip"
 ```
 

docs/config/internal/type-checking.md

@@ -0,0 +1,65 @@
+# Type checking configuration
+
+-----
+
+Type checking performed by the [`check types`](../../cli/reference.md#hatch-check-types) command is ([by default](#customize-behavior)) backed by [Pyrefly](https://github.com/facebook/pyrefly).
+
+## Configuration
+
+When no user configuration is detected, Hatch auto-generates a `pyrefly.toml` config file that:
+
+- Detects source directories (src layout, workspace members, tests)
+- Sets appropriate search paths for import resolution
+- Uses the `legacy` preset for relaxed type checking suitable for existing codebases
+- Ignores platform-conditional dependencies that aren't installed locally
+
+### User configuration
+
+Hatch respects existing Pyrefly configuration. If any of the following exist, the auto-generated config will not be used:
+
+- A `pyrefly.toml` file in the project root
+- A `[tool.pyrefly]` section in `pyproject.toml`
+
+### Persistent config
+
+If you want to store the default configuration in the project, set an explicit path:
+
+```toml config-example
+[tool.hatch.envs.hatch-check-types]
+config-path = "pyrefly.toml"
+```
+
+## Customize behavior
+
+You can fully alter the behavior of the environment used by the [`check types`](../../cli/reference.md#hatch-check-types) command by modifying the reserved [environment](../../config/environment/overview.md) named `hatch-check-types`.
+
+### Dependencies
+
+The environment includes Pyrefly and all test dependencies (inherited from the `hatch-test` environment) to ensure type checking has access to all imports. Pin the particular version of Pyrefly by explicitly defining the environment [dependencies](../environment/overview.md#dependencies):
+
+```toml config-example
+[tool.hatch.envs.hatch-check-types]
+dependencies = ["pyrefly==X.Y.Z"]
+```
+
+### Scripts
+
+If you want to change the default commands that are executed, you can override the [scripts](../environment/overview.md#scripts):
+
+```toml config-example
+[tool.hatch.envs.hatch-check-types.scripts]
+check = "..."
+check-summarize = "..."
+coverage = "..."
+```
+
+The `check` script runs by default. The `check-summarize` script runs when the `--summarize` flag is passed. The `coverage` script runs when the `--cover` flag is passed.
+
+### Installer
+
+By default, [UV is enabled](../../how-to/environment/select-installer.md). You may disable that behavior as follows:
+
+```toml config-example
+[tool.hatch.envs.hatch-check-types]
+installer = "pip"
+```

docs/history/hatch.md

@@ -8,6 +8,27 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## Unreleased
 
+***Changed:***
+
+- The `hatch fmt` command is now deprecated in favor of the new `hatch check` command group
+- Migrate HTTP client from `httpx` to `httpx2`
+
+***Added:***
+
+- Add `hatch check` command group with subcommands for `check code` (linting), `check fmt` (formatting), and `check types` (type checking)
+- Add `hatch check types` command for type checking using Pyrefly, with `--summarize` and `--cover` flags
+- Add `hatch env lock` command to generate PEP 751 compliant lockfiles (`pylock.toml`) for environments
+- Add `hatch dep lock` and `hatch lock` commands as shortcuts for locking the active environment
+- Add `hatch dep sync` command for syncing dependencies from a lockfile
+- Add pluggable dependency locker interface with built-in UV and pip implementations
+- Add `--cover-xml` and `--cover-xml-output` flags to the `hatch test` command for generating XML coverage reports
+- Add linehaul telemetry data to User-Agent header for PyPI download statistics
+- Auto-create environment when locking if it doesn't exist
+
+***Fixed:***
+
+- Fix help output formatting for the `run` command
+
 ## [1.16.5](https://github.com/pypa/hatch/releases/tag/hatch-v1.16.5) - 2026-02-26 ## {: #hatch-v1.16.5 }
 
 ***Fixed:***

docs/history/hatchling.md

@@ -12,6 +12,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - Support PEP 794 (core metadata `Import-Name` and `Import-Namespace` fields and version 2.5)
 
+***Fixed:***
+
+- Exclude Git worktree metadata files from sdists
+
 ## [1.29.0](https://github.com/pypa/hatch/releases/tag/hatchling-v1.29.0) - 2026-02-21 ## {: #hatchling-v1.29.0 }
 
 ***Fixed:***

docs/how-to/run/python-scripts.md

@@ -17,15 +17,15 @@ The following is an example of Python script with a valid metadata block:
 # /// script
 # requires-python = ">=3.11"
 # dependencies = [
-#   "httpx",
+#   "httpx2",
 #   "rich",
 # ]
 # ///
 
-import httpx
+import httpx2
 from rich.pretty import pprint
 
-resp = httpx.get("https://peps.python.org/api/peps.json")
+resp = httpx2.get("https://peps.python.org/api/peps.json")
 data = resp.json()
 pprint([(k, v["title"]) for k, v in data.items()][:10])
 ```