shahar1 opened a new issue, #74914: URL: https://github.com/apache/airflow/issues/74914
### Body The license header at the top of our `*.rst` files comes in three shapes, and the `insert-license` prek hook accepts all of them, so contributors who touch a file see a mix and guess. This surfaced in https://github.com/apache/airflow/pull/74804, where a review thread spent time on whether a leading blank line is required by the license check (it is not), and which of the existing styles is the "right" one. That is not a question a feature PR should have to answer, so this issue tracks fixing it repo-wide. Census on `main` (`git ls-files '*.rst'`, 1759 files): | First line of the file | Files | Example | |---|---|---| | ` .. Licensed to the Apache ...` (one leading space, 4-space continuation) | 1250 | `BREEZE.rst` | | blank line, header starts on line 2 at column 0 | 356 | `providers/common/ai/docs/index.rst`, `airflow-core/docs/operators-and-hooks-ref.rst` | | `.. Licensed to the Apache ...` at column 0 (3- or 4-space continuation) | 77 | `COMMITTERS.rst`, `providers/snowflake/docs/connections/snowflake.rst` | | no header (newsfragments, excluded by the hook) | 76 | `airflow-core/newsfragments/*.rst` | Why it happens: the hook (`Add license for all RST files` in `.pre-commit-config.yaml`) runs `insert-license` with `--comment-style "||"`, `--license-filepath scripts/ci/license-templates/LICENSE.rst` and `--fuzzy-match-generates-todo`. When it inserts a header it writes the first shape (verified: a fresh file gets ` .. Licensed ...` with a leading space). When a file already carries any of the three shapes, the fuzzy match passes and nothing is rewritten, so the variants never converge. Verified on the file from the PR above: the hook reports `Passed` both with and without the leading blank line. Proposal: 1. Pick one canonical shape. The hook's own output (` .. Licensed ...`, 4-space continuation) is the natural choice because new files get it automatically; `scripts/ci/license-templates/LICENSE.rst` and `contributing-docs/08_static_code_checks.rst` should state it. 2. One mechanical PR that rewrites the 433 non-canonical files (356 blank-first-line + 77 column-0). The header is an rst comment, so rendered docs do not change. Doing it in one go, or one PR per top-level area, keeps the conflict window short for open PRs. 3. Make the check strict so the shapes cannot drift again: either drop `--fuzzy-match-generates-todo` for rst (so a non-exact header is treated as missing and the hook rewrites it), or add a small prek script that fails when an rst file's header does not start on line 1 with the canonical text. Acceptance criteria: every tracked `*.rst` outside the hook's exclusions starts with the identical canonical header on line 1, and the static check fails on a file that deviates. --- Drafted-by: Claude Code (Fable 5.1) (no human review before posting) ### Committer - [X] I acknowledge that I am a maintainer/committer of the Apache Airflow project. -- 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]
