Update docs site for version 2.25.0.dev1

docs/docs/getting-started/installing-pants.mdx

@@ -35,16 +35,14 @@ bin i github.com/pantsbuild/scie-pants ~/.local/bin/pants
 
 If you have difficulty installing Pants, see our [getting help](/community/getting-help) for community resources to help you resolve your issue.
 
-:::tip Upgrading Pants
+## Upgrading Pants
+
 The `pants` launcher binary will automatically install and use the Pants version specified in `pants.toml`, so upgrading Pants in a repo is as simple as editing `pants_version` in that file.
 
-To upgrade the `pants` launcher binary itself, run
+To upgrade the `pants` launcher binary itself, either:
 
-```
-SCIE_BOOT=update pants
-```
-
-:::
+- Use the package manager you used to install Pants. For example, with Homebrew: `brew update && brew upgrade pantsbuild/tap/pants`.
+- Use its built-in self-update functionality: `SCIE_BOOT=update pants`.
 
 ## Running Pants from sources
 

docs/docs/python/integrations/protobuf-and-grpc.mdx

@@ -152,7 +152,17 @@ from project.example.f_pb2_grcp import GreeterServicer
 
 You do not need to run this goal for codegen to work when using Pants; `export-codegen` is only for external consumption outside of Pants.
 
-Note: You can also export the generated sources using the [`--export-py-generated-sources` option](../../../reference/goals/export#py_generated_sources) to the [`pants export` goal](../../../reference/goals/export). This is useful when you want to provide an IDE with third-party dependencies and generated sources in a single place.
+Note: You can also export the generated sources using the [`--export-py-generated-sources-in-resolve`](../../..//reference/goals/export#py_generated_sources_in_resolve) option to the [`pants export`](../../../reference/goals/export) goal. This is useful when you want to provide an IDE with third-party dependencies and generated sources in a single place.
+
+For example,
+
+```bash
+❯ pants export \
+    --resolve=python-default \
+    --export-py-generated-sources-in-resolve=python-default
+```
+
+This assumes that you have a `resolve` named `python-default` (see [Getting started with resolves](../overview/lockfiles.mdx#getting-started-with-resolves)). For a concrete example of a project that sets a resolve named `python-default` see this [example `pants.toml`](https://github.com/pantsbuild/example-python/blob/main/pants.toml).
 :::
 
 :::caution You likely need to add empty `__init__.py` files

docs/docs/python/integrations/thrift.mdx

@@ -114,7 +114,17 @@ For example, compare `import user.ttypes` to `import codegen.models.user.ttypes`
 
 You do not need to run this goal for codegen to work when using Pants; `export-codegen` is only for external consumption outside of Pants.
 
-Note: You can also export the generated sources using the [`--export-py-generated-sources` option](../../../reference/goals/export#py_generated_sources) to the [`pants export` goal](../../../reference/goals/export). This is useful when you want to provide an IDE with third-party dependencies and generated sources in a single place.
+Note: You can also export the generated sources using the `--export-py-generated-sources-in-resolve` option to the `pants export` goal. This is useful when you want to provide an IDE with third-party dependencies and generated sources in a single place.
+
+For example,
+
+```bash
+❯ pants export \
+    --resolve=python-default \
+    --export-py-generated-sources-in-resolve=python-default
+```
+
+This assumes that you have a `resolve` named `python-default` (see [Getting started with resolves](../overview/lockfiles.mdx#getting-started-with-resolves)). For a concrete example of a project that sets a resolve named `python-default` see this [example `pants.toml`](https://github.com/pantsbuild/example-python/blob/main/pants.toml).
 :::
 
 ## Multiple resolves

docs/reference/build-file-symbols/__defaults__.mdx

@@ -10,6 +10,6 @@ import BuildFileSymbol from "@site/src/components/reference/BuildFileSymbol";
 
 Provide default field values.
 
-Learn more https://www.pantsbuild.org/2.24/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
+Learn more https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/targets-and-build-files#field-default-values
 
 </BuildFileSymbol>

docs/reference/global-options.mdx

@@ -139,33 +139,6 @@ Run goals continuously as file changes are detected.
 
 </Option>
 
-### `native_options_validation`
-
-<Option
-  cli_repr={`--native-options-validation=<NativeOptionsValidation>`}
-  env_repr='PANTS_NATIVE_OPTIONS_VALIDATION'
-  toml_repr={`[GLOBAL]
-native_options_validation = <NativeOptionsValidation>`}
-  one_of='ignore, warning, error'
-  default_repr={`warning`}
->
-
-Pants is switching its option parsing system from a legacy parser written in Python to a new one written in Rust.
-
-The results of parsing a given option by each system should be identical. However during a transition period we will run both parsers and compare their results. This option controls how to report discrepancies that arise.
-
-- `error`: Discrepancies will cause Pants to exit.
-
-- `warning`: Discrepancies will be logged but Pants will continue.
-
-- `ignore`: A last resort to turn off this check entirely.
-
-If you encounter discrepancies that are not easily resolvable, please reach out to us on Slack or file an issue: https://www.pantsbuild.org/community/getting-help.
-
-The native parser will become the default in 2.23.x, and the legacy parser will be removed in 2.24.x. So it is imperative that we find out about any discrepancies during this transition period.
-
-</Option>
-
 ### `pantsd`
 
 <Option
@@ -239,7 +212,7 @@ remote_provider = <RemoteProvider>`}
   default_repr={`reapi`}
 >
 
-The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.24/docs/using-pants/remote-caching-and-execution for details.
+The type of provider to use, if using a remote cache and/or remote execution, See https://www.pantsbuild.org/2.25/docs/using-pants/remote-caching-and-execution for details.
 
 Each provider supports different `remote_store_address` and (optional) `remote_execution_address` URIs.
 
@@ -299,7 +272,7 @@ tag = [
   default_repr={`[]`}
 >
 
-Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.24/docs/using-pants/advanced-target-selection.
+Include only targets with these tags (optional &#x27;+&#x27; prefix) or without these tags (&#x27;-&#x27; prefix). See https://www.pantsbuild.org/2.25/docs/using-pants/advanced-target-selection.
 
 </Option>
 
@@ -359,7 +332,7 @@ build_file_prelude_globs = [
   default_repr={`[]`}
 >
 
-Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.24/docs/writing-plugins/macros.
+Python files to evaluate and whose symbols should be exposed to all BUILD files. See https://www.pantsbuild.org/2.25/docs/writing-plugins/macros.
 
 </Option>
 
@@ -419,7 +392,7 @@ Path to a file containing PEM-format CA certificates used for verifying secure c
 
 Even when using the `docker_environment` and `remote_environment` targets, this path will be read from the local host, and those certs will be used in the environment.
 
-This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.24/docs/using-pants/key-concepts/options.
+This option cannot be overridden via environment targets, so if you need a different value than what the rest of your organization is using, override the value via an environment variable, CLI argument, or `.pants.rc` file. See https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options.
 
 </Option>
 
@@ -845,7 +818,7 @@ pants_version = <str>`}
 
 Use this Pants version. Note that Pants only uses this to verify that you are using the requested version, as Pants cannot dynamically change the version it is using once the program is already running.
 
-If you use the `pants` script from https://www.pantsbuild.org/2.24/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
+If you use the `pants` script from https://www.pantsbuild.org/2.25/docs/getting-started/installing-pants, however, changing the value in your `pants.toml` will cause the new version to be installed and run automatically.
 
 Run `pants --version` to check what is being used.
 
@@ -1295,7 +1268,7 @@ If you are using the `remote_environment` target mechanism, set this value as a
 key1 = val1
 key2 = val2
 ...`}
-  default_repr={`{'user-agent': 'pants/<pants_version>'}`}
+  default_repr={`{}`}
 >
 
 Headers to set on remote execution requests. Format: header=value. Pants may add additional headers.
@@ -1364,7 +1337,7 @@ An oauth token to use for gGRPC connections to `[GLOBAL].remote_execution_addres
 
 If specified, Pants will add a header in the format `authorization: Bearer <token>`. You can also manually add this header via `[GLOBAL].remote_execution_headers` and `[GLOBAL].remote_store_headers`, or use `[GLOBAL].remote_auth_plugin` to provide a plugin to dynamically set the relevant headers. Otherwise, no authorization will be performed.
 
-Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.24/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
+Recommendation: do not place a token directly in `pants.toml`, instead do one of: set the token via the environment variable (`PANTS_REMOTE_OAUTH_BEARER_TOKEN`), CLI option (`--remote-oauth-bearer-token`), or store the token in a file and set the option to `"@/path/to/token.txt"` to [read the value from that file](https://www.pantsbuild.org/2.25/docs/using-pants/key-concepts/options#reading-individual-option-values-from-files).
 
 </Option>
 
@@ -1419,7 +1392,7 @@ Size in bytes of chunks transferred to/from the remote file store.
 key1 = val1
 key2 = val2
 ...`}
-  default_repr={`{'user-agent': 'pants/<pants_version>'}`}
+  default_repr={`{}`}
 >
 
 Headers to set on remote store requests.
@@ -1681,6 +1654,35 @@ If you have questions or concerns about this, please reach out to us at https://
 
 </Option>
 
+### `native_options_validation`
+
+<Option
+  cli_repr={`--native-options-validation=<NativeOptionsValidation>`}
+  env_repr='PANTS_NATIVE_OPTIONS_VALIDATION'
+  toml_repr={`[GLOBAL]
+native_options_validation = <NativeOptionsValidation>`}
+  one_of='ignore, warning, error'
+  default_repr={`warning`}
+  removal_version='2.26.0.dev0'
+  removal_hint={'The legacy parser has been removed so this option has no effect.'}
+>
+
+Pants is switching its option parsing system from a legacy parser written in Python to a new one written in Rust.
+
+The results of parsing a given option by each system should be identical. However during a transition period we will run both parsers and compare their results. This option controls how to report discrepancies that arise.
+
+- `error`: Discrepancies will cause Pants to exit.
+
+- `warning`: Discrepancies will be logged but Pants will continue.
+
+- `ignore`: A last resort to turn off this check entirely.
+
+If you encounter discrepancies that are not easily resolvable, please reach out to us on Slack or file an issue: https://www.pantsbuild.org/community/getting-help.
+
+The native parser will become the default in 2.23.x, and the legacy parser will be removed in 2.24.x. So it is imperative that we find out about any discrepancies during this transition period.
+
+</Option>
+
 ### `process_cleanup`
 
 <Option

docs/reference/goals/tailor.mdx

@@ -53,7 +53,7 @@ key2 = val2
   default_repr={`{}`}
 >
 
-A mapping from standard target type to custom type to use instead. The custom type can be a custom target type or a macro that offers compatible functionality to the one it replaces (see https://www.pantsbuild.org/2.24/docs/writing-plugins/macros).
+A mapping from standard target type to custom type to use instead. The custom type can be a custom target type or a macro that offers compatible functionality to the one it replaces (see https://www.pantsbuild.org/2.25/docs/writing-plugins/macros).
 
 </Option>
 

docs/reference/goals/update-build-files.mdx

@@ -15,7 +15,7 @@ pants update-build-files [args]
 
 Format and fix safe deprecations in BUILD files.
 
-This does not handle the full Pants upgrade. You must still manually change `pants_version` in `pants.toml` and you may need to manually address some deprecations. See https://www.pantsbuild.org/2.24/docs/releases/upgrade-tips for upgrade tips.
+This does not handle the full Pants upgrade. You must still manually change `pants_version` in `pants.toml` and you may need to manually address some deprecations. See https://www.pantsbuild.org/2.25/docs/releases/upgrade-tips for upgrade tips.
 
 Backend: <span className="color--primary">`pants.core`</span>