xchwan opened a new pull request, #75838:
URL: https://github.com/apache/airflow/pull/75838
<!-- SPDX-License-Identifier: Apache-2.0
https://www.apache.org/licenses/LICENSE-2.0 -->
<!--
Thank you for contributing!
Please provide above a brief description of the changes made in this pull
request.
Write a good git commit message following this guide:
https://chris.beams.io/posts/git-commit/
Please make sure that your code changes are covered with tests.
And in case of new features or big changes remember to adjust the
documentation.
For user-facing UI changes, please attach before/after screenshots (or a
short
screen recording) so reviewers can assess the visual impact.
Feel free to ping (in general) for the review if you do not see reaction for
a few days
(72 Hours is the minimum reaction time you can expect from volunteers) - we
sometimes miss notifications.
In case of an existing issue, reference it using one of the following:
* closes: #ISSUE
* related: #ISSUE
-->
---
The license header in `*.rst` files came in several shapes (leading blank
line, no indentation, canonical). The `insert-license` hook strips whitespace
and looks for the header in the first few lines, so it accepts all of them and
the shapes never converged.
This adds a `check-rst-license-header` hook that requires the header on line
1 with every non-empty line indented by one space, which is what
`insert-license` writes for a new file. The hook rewrites a header that is only
a blank line or indentation away from that shape, and reports a header that has
other content before it. The canonical text is derived from
`scripts/ci/license-templates/LICENSE.rst`. Dropping
`--fuzzy-match-generates-todo` was not enough: the match ignores whitespace
whether or not that flag is set.
The rewrite of the existing files is the hook's own output, as agreed on the
issue
([comment](https://github.com/apache/airflow/issues/74914#issuecomment-6454208426)).
### What to review
The change is large because of the rewritten files, but the logic is in four
files:
- `scripts/ci/prek/check_rst_license_header.py`: the hook.
- `scripts/tests/ci/prek/test_check_rst_license_header.py`: its tests.
- `.pre-commit-config.yaml`: the hook entry, with the same `files`/`exclude`
as the existing RST license hook.
- `contributing-docs/08_static_code_checks.rst`: documents the canonical
shape.
The other `*.rst` files only change their header lines. To reproduce them,
run on `main`:
`prek run check-rst-license-header --all-files`
### Exceptions
Four files need more than the hook's own rewrite:
- `airflow-core/docs/cli-and-env-variables-ref.rst`: left unchanged. It
starts with `:tocdepth: 4`, and an indented header is parsed as a block quote,
so putting the header first stops the field list from being read as document
metadata and `tocdepth` would be lost. The hook skips it.
- `airflow-ctl/docs/cli-and-env-variables-ref.rst`: left unchanged, same
reason. The hook skips it.
- `contributing-docs/05_pull_requests.rst`: removed a stray first line (the
file's own path). Together with the indented header it parsed as a definition
list, so that line was rendered at the top of the page.
- `providers/google/docs/operators/cloud/bigquery.rst`: removed a duplicated
first header line. The rendered page does not change.
### How the rewrite was checked
- For each changed file, the content after the header is identical before
and after.
- Parsing every changed file with docutils (title promotion off, as in
Sphinx) gives the same document tree before and after, ignoring comments, empty
block quotes and line numbers.
- A second run of the hook changes nothing.
- `prek run --stage pre-commit` passes on the changed files.
- `breeze build-docs apache-airflow --one-pass-only` finishes successfully
with no warnings or errors. The other documentation packages were not built.
Open PRs that add or edit `*.rst` files with a different header shape will
have the hook rewrite their header on their next run.
closes: #74914
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes (Claude Code)
Generated-by: Claude Code (Sonnet 5.5) following [the
guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
---
* Read the **[Pull Request
Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)**
for more information. Note: commit author/co-author name and email in commits
become permanently public when merged.
* For fundamental code changes, an Airflow Improvement Proposal
([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals))
is needed.
* When adding dependency, check compliance with the [ASF 3rd Party License
Policy](https://www.apache.org/legal/resolved.html#category-x).
* For significant user-facing changes create newsfragment:
`{pr_number}.significant.rst`, in
[airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments).
You can add this file in a follow-up commit after the PR is created so you
know the PR number.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
