1"""Release notes: the one-answer query the release train writes notes through.
3A release stamps a version, and a package's history says what the
4version holds. The train never writes that history itself: it asks
5the provider the listed extensions answer the ``release-notes`` query
6with for the entry the unreleased commits earn, has the provider
7record it, and has it judge the recorded notes before a tag is cut. A
8workspace whose extensions answer nothing releases without notes, and
9the train says so where it would have written them.
11One answer at a time: the query combines by ``nearest``, so two
12listed extensions answering, neither requiring the other, refuse
13naming both.
14"""
23 from pathlib import Path
25 from livery.workshop._packages import Package
29 """What a release-notes provider answers."""
32 """The notes the commits since *package*'s last release earn.
34 Headed by *version* when one is given, as unreleased otherwise;
35 empty when nothing unreleased touches the package.
36 """
37 ...
40 """Write *version*'s *entry* into *package*'s history.
42 An empty *entry* records a placeholder for a person to write.
43 Returns the files changed, each with a note for the reader,
44 empty when the history already holds the version's entry.
45 """
46 ...
49 """The problems with *version*'s recorded notes; empty when sound."""
50 ...
53#: The release notes' provider, a workspace-level query the base
54#: declares; the extension that writes the history answers it with a
55#: function called with the workspace root.
60 """The provider the extensions listed at *root* answer; None when none answers.
62 The answer is imported when first asked, so a mount imports none
63 of the answering extension's code.
65 Raises:
66 QueryError: when two listed extensions answer and neither
67 requires the other, naming both.
68 """
69 return answer(root, RELEASE_NOTES)
72#: What the train prints where it would have written notes and has no provider.