{"record":{"id":"e6205650a0c5aa48","repo":"tiangolo/fastapi","slug":"release-notes-file-must-start-with-release-note","errorCode":null,"errorMessage":"{release_notes_file} must start with {RELEASE_NOTES_HEADER!r}","messagePattern":"(.+?) must start with (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"scripts/prepare_release.py","lineNumber":66,"sourceCode":"    if bump == \"minor\":\n        return f\"{major}.{minor + 1}.0\"\n    return f\"{major}.{minor}.{patch + 1}\"\n\n\ndef update_version_file(content: str, version: str, version_file: Path) -> str:\n    current_version = get_current_version(content, version_file)\n    if parse_version(version) <= parse_version(current_version):\n        raise RuntimeError(\n            f\"New version {version} must be greater than current version {current_version}\"\n        )\n    return VERSION_PATTERN.sub(f'__version__ = \"{version}\"', content, count=1)\n\n\ndef update_release_notes(\n    content: str, version: str, release_date: date, release_notes_file: Path\n) -> str:\n    if not content.startswith(RELEASE_NOTES_HEADER):\n        raise RuntimeError(\n            f\"{release_notes_file} must start with {RELEASE_NOTES_HEADER!r}\"\n        )\n    if re.search(rf\"^## {re.escape(version)}(?: \\([^)]+\\))?$\", content, re.M):\n        raise RuntimeError(f\"Release notes already contain a section for {version}\")\n\n    latest_header = f\"{RELEASE_NOTES_HEADER}{LATEST_CHANGES_HEADER}\\n\"\n    if not content.startswith(latest_header):\n        raise RuntimeError(f\"{release_notes_file} must start with {latest_header!r}\")\n\n    release_header = f\"## {version} ({release_date.isoformat()})\"\n    return content.replace(\n        latest_header,\n        f\"{RELEASE_NOTES_HEADER}{LATEST_CHANGES_HEADER}\\n\\n{release_header}\\n\",\n        1,\n    )\n\n\ndef get_release_notes_body(content: str, version: str, release_notes_file: Path) -> str:","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/tiangolo/fastapi/blob/3e8d1526d83a90aaf7d6eb6dc682bf150f180b25/scripts/prepare_release.py#L48-L84","documentation":"Raised by update_release_notes() in scripts/prepare_release.py:66 when the release-notes Markdown file does not start with the exact RELEASE_NOTES_HEADER (front matter hiding navigation, a blank line, '# Release Notes', blank line — scripts/prepare_release.py:12-19). This header is the anchor used to splice in new version sections, so a missing or altered header would misplace new entries.","triggerScenarios":"Calling prepare when release_notes_file (docs/en/docs/release-notes.md typically) has had its front-matter block edited, the '# Release Notes' title changed, or trailing whitespace/newlines disturbed the exact prefix match at scripts/prepare_release.py:65.","commonSituations":"A doc tool reformatted the front matter. The title was translated or renamed. A blank line was removed between front matter and the H1.","solutions":["Open the release notes file and restore the exact header block: '---\\nhide:\\n  - navigation\\n---\\n\\n# Release Notes\\n\\n'.","Restore from git history if unsure of the exact bytes.","Re-run prepare."],"exampleFix":"<!-- before -->\n# Release Notes\n<!-- after -->\n---\nhide:\n  - navigation\n---\n\n# Release Notes\n\n","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nRELEASE_NOTES_HEADER = \"---\\nhide:\\n  - navigation\\n---\\n\\n# Release Notes\\n\\n\"\n\ndef notes_header_ok(path: Path) -> bool:\n    return path.read_text(encoding=\"utf-8\").startswith(RELEASE_NOTES_HEADER)","typeGuard":null,"tryCatchPattern":"try:\n    updated = update_release_notes(content, version, d, release_notes_file)\nexcept RuntimeError as e:\n    if \"must start with\" in str(e):\n        raise SystemExit(f\"Release notes header malformed: {e}\") from e\n    raise","preventionTips":["Treat the release-notes front matter + '# Release Notes' header as immutable scaffolding.","Add a CI assertion that the file starts with RELEASE_NOTES_HEADER.","Avoid formatters that rewrite YAML front matter."],"tags":["release","docs","validation","markdown"],"backgroundTag":null,"analyzedSha":"3e8d1526d83a90aaf7d6eb6dc682bf150f180b25","analyzedAt":"2026-08-11T02:34:52.986Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}