feat: Add a setting to disallow hard-coding some setting keys in the pyproject.toml

[LecrisUT]

This complements the discussion in #1050 that we should not allow some fields to be hard-coded. We should allow them in the context of overrides, so here is a rather convoluted way of adding that check.

This will also make it possible to extend it further if we want more specific checks for specific overrides matchers as well. E.g. we can add a restriction that build.requires cannot have @ in an sdist

[jcfr]

Following discussion with @henryiii during Note from community meeting. Ideally, the schema should be updated before integrating.

[Copilot]

Pull Request Overview

This PR adds a mechanism to disallow hard-coding certain settings keys (like fail) in the top-level pyproject.toml, while still allowing them in override contexts. The fail field is the first to use this new override_only metadata flag.

Key Changes

• Introduced override_only metadata field for settings that should only appear in overrides
• Added validation logic to check for hard-coded override_only fields and warn/error accordingly
• Updated fail field to use Optional[bool] with default None and marked as override_only

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/scikit_build_core/settings/skbuild_model.py	Changed fail field to Optional[bool] with override_only=True metadata
src/scikit_build_core/settings/skbuild_overrides.py	Added OverrideRecord dataclass and record_override function to track override history
src/scikit_build_core/settings/skbuild_read_settings.py	Added _validate_overrides function to validate override_only fields
src/scikit_build_core/settings/skbuild_schema.py	Updated schema generation to exclude override_only properties from top-level schema
src/scikit_build_core/settings/json_schema.py	Added scikit-build:override-only marker to JSON schema properties
src/scikit_build_core/settings/documentation.py	Added override_only field to DCDoc dataclass
src/scikit_build_core/settings/skbuild_docs_readme.py	Filtered out override_only items from README documentation
src/scikit_build_core/resources/scikit-build.schema.json	Removed default: false from fail property and updated schema structure
tests/test_settings_overrides.py	Added test for disallow hardcoded functionality
tests/test_settings_docs.py	Updated assertion to verify fail is not in documentation
docs/reference/configs.md	Removed default value from fail configuration documentation
README.md	Removed fail = false from example configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[henryiii]

Note this is a very slight breaking change; if someone put fail = false explicitly at the top level, now that will be an error unless strictness is turned off. I think that's fine though, as it should be quite rare to do that, and easy to fix. We could put a workaround for this case for a while if really needed, though.