def append_changelog_changes_ansible(
builder: RstBuilder, changelog_entry: ChangelogEntry) -> PluginDataT:
changelog = changelog_entry.ansible_changelog
release_entries = changelog.generator.collect(
squash=True,
after_version=str(changelog_entry.prev_version)
if changelog_entry.prev_version else None,
until_version=changelog_entry.version_str)
if not release_entries:
return []
release_entry = release_entries[0]
release_summary = release_entry.changes.pop('release_summary', None)
if release_summary:
builder.add_section('Release Summary', 1)
builder.add_raw_rst(t.cast(str, release_summary))
builder.add_raw_rst('')
if release_entry.empty:
return []
return [("", "", changelog.generator, release_entry)]
def append_removed_collections(builder: RstBuilder, changelog_entry: ChangelogEntry) -> None:
if changelog_entry.removed_collections:
builder.add_section('Removed Collections', 1)
for collector, collection_version in changelog_entry.removed_collections:
builder.add_list_item(f"{collector.collection} "
f"(previously included version: {collection_version})")
builder.add_raw_rst('')
def append_unchanged_collections(builder: RstBuilder,
changelog_entry: ChangelogEntry) -> None:
if changelog_entry.unchanged_collections:
builder.add_section('Unchanged Collections', 1)
for collector, collection_version in changelog_entry.unchanged_collections:
builder.add_list_item(
f"{collector.collection} (still version {collection_version})")
builder.add_raw_rst('')
def append_changelog_changes_collections(builder: RstBuilder,
collection_metadata: CollectionsMetadata,
changelog_entry: ChangelogEntry,
is_last: bool) -> PluginDataT:
result: PluginDataT = []
if changelog_entry.changed_collections:
builder.add_section('Included Collections' if is_last else 'Changed Collections', 1)
builder.add_raw_rst(
'If not mentioned explicitly, the changes are reported in the combined changelog'
' below.\n')
headings = [
'Collection',
f'Ansible {changelog_entry.prev_version}',
f'Ansible {changelog_entry.version_str}',
'Notes'
]
cells = []
for (
collector, collection_version, prev_collection_version
) in changelog_entry.changed_collections:
row = [collector.collection, '', str(collection_version), '']
if prev_collection_version is not None:
row[1] = str(prev_collection_version)
changelog = collector.changelog
if changelog:
release_entries = changelog.generator.collect(
squash=True,
after_version=prev_collection_version,
until_version=collection_version)
if not release_entries:
row[-1] = "The collection did not have a changelog in this version."
elif release_entries[0].empty:
row[-1] = "There are no changes recorded in the changelog."
else:
result.append((
collector.collection,
f"{collector.collection}.",
changelog.generator,
optimize_release_entry(release_entries[0])))
else:
metadata = collection_metadata.get_meta(collector.collection)
if metadata.changelog_url is not None:
row[-1] = (
"You can find the collection's changelog at"
f" `{metadata.changelog_url} <{metadata.changelog_url}>`_."
)
else:
row[-1] = (
"Unfortunately, this collection does not provide changelog data in a"
" format that can be processed by the changelog generator."
)
cells.append(row)
render_rst_table(builder, headings, cells)
builder.add_raw_rst('')
return result
def append_changelog_changes_collections(builder: RstBuilder,
collection_metadata: CollectionsMetadata,
changelog_entry: ChangelogEntry,
is_last: bool) -> PluginDataT:
result: PluginDataT = []
if changelog_entry.changed_collections:
builder.add_section('Included Collections' if is_last else 'Changed Collections', 1)
for (
collector, collection_version, prev_collection_version
) in changelog_entry.changed_collections:
if is_last:
msg = f"{collector.collection} with version {collection_version}."
if prev_collection_version is not None:
msg += f" This was upgraded from version {prev_collection_version}."
else:
if prev_collection_version is None:
msg = f"{collector.collection} was upgraded to version {collection_version}."
else:
msg = f"{collector.collection} was upgraded from"
msg += f" version {prev_collection_version} to version {collection_version}."
msg += "\n"
changelog = collector.changelog
if changelog:
release_entries = changelog.generator.collect(
squash=True,
after_version=prev_collection_version,
until_version=collection_version)
if not release_entries:
msg += "The collection did not have a changelog in this version."
elif release_entries[0].empty:
msg += "There are no changes recorded in the changelog."
else:
result.append((
collector.collection,
f"{collector.collection}.",
changelog.generator,
release_entries[0]))
msg += "The changes are reported in the combined changelog below."
else:
metadata = collection_metadata.get_meta(collector.collection)
if metadata.changelog_url is not None:
msg += "You can find the collection's changelog at"
msg += f" `{metadata.changelog_url} <{metadata.changelog_url}>`_."
else:
msg += "Unfortunately, this collection does not provide changelog data in a"
msg += " format that can be processed by the changelog generator."
builder.add_list_item(msg)
builder.add_raw_rst('')
return result
def dump_plugins(builder: RstBuilder, plugins: PluginDumpT) -> None:
last_title = []
for title, name, description in sorted(plugins):
if title != last_title:
if last_title:
builder.add_raw_rst('')
for i in range(common_start(last_title, title), len(title)):
builder.add_section(title[i], i + 1)
last_title = title
builder.add_list_item(f"{name} - {description}")
if last_title:
builder.add_raw_rst('')
def append_changelog(builder: RstBuilder,
collection_metadata: CollectionsMetadata,
changelog_entry: ChangelogEntry, is_last: bool) -> None:
builder.add_section('v{0}'.format(changelog_entry.version_str), 0)
builder.add_raw_rst('.. contents::')
builder.add_raw_rst(' :local:')
builder.add_raw_rst(' :depth: 2\n')
# Add release summary for Ansible
data = append_changelog_changes_ansible(builder, changelog_entry)
append_removed_collections(builder, changelog_entry)
append_added_collections(builder, changelog_entry)
# Adds Ansible-base section
data.extend(append_changelog_changes_base(builder, changelog_entry))
builder.add_raw_rst('')
# Adds list of changed collections
data.extend(
append_changelog_changes_collections(builder,
collection_metadata,
changelog_entry,
is_last=is_last))
# Adds all changes
for section, section_title in DEFAULT_SECTIONS:
maybe_add_section_title = create_title_adder(builder, section_title, 1)
for name, dummy, dummy, release_entry in data:
if not release_entry or release_entry.has_no_changes([section]):
continue
next(maybe_add_section_title)
if name:
builder.add_section(name, 2)
release_entry.add_section_content(builder, section)
builder.add_raw_rst('')
# Adds new plugins and modules
add_plugins(builder, data)
add_modules(builder, data)
add_objects(builder, data)
# Adds list of unchanged collections
append_unchanged_collections(builder, changelog_entry)
def append_changelog_changes_base(
builder: RstBuilder, changelog_entry: ChangelogEntry) -> PluginDataT:
base_name = 'Ansible-base'
if (changelog_entry.base_collector.latest.major > 2
or changelog_entry.base_collector.latest.minor > 10):
base_name = 'Ansible-core'
builder.add_section(base_name, 1)
builder.add_raw_rst(
f"Ansible {changelog_entry.version} contains {base_name} "
f"version {changelog_entry.ansible_base_version}.")
if changelog_entry.prev_ansible_base_version:
if changelog_entry.prev_ansible_base_version == changelog_entry.ansible_base_version:
builder.add_raw_rst(
f"This is the same version of {base_name} as in "
"the previous Ansible release.\n")
return []
builder.add_raw_rst(
f"This is a newer version than version "
f"{changelog_entry.prev_ansible_base_version} contained in the "
f"previous Ansible release.\n")
changelog = changelog_entry.base_collector.changelog
if not changelog:
return []
release_entries = changelog.generator.collect(
squash=True,
after_version=changelog_entry.prev_ansible_base_version,
until_version=changelog_entry.ansible_base_version)
if not release_entries:
builder.add_raw_rst(
f"{base_name} did not have a changelog in this version.")
return []
release_entry = release_entries[0]
if release_entry.empty:
builder.add_raw_rst("There are no changes recorded in the changelog.")
return []
builder.add_raw_rst(
"The changes are reported in the combined changelog below.")
return [(base_name, "ansible.builtin.", changelog.generator, release_entry)
]
def append_porting_guide(builder: RstBuilder, changelog_entry: ChangelogEntry) -> None:
maybe_add_title = create_title_adder(
builder, 'Porting Guide for v{0}'.format(changelog_entry.version_str), 0)
for section in ['known_issues', 'breaking_changes', 'major_changes']:
append_porting_guide_section(builder, changelog_entry, maybe_add_title, section)
if changelog_entry.removed_collections:
next(maybe_add_title)
builder.add_section('Removed Collections', 1)
for collector, collection_version in changelog_entry.removed_collections:
builder.add_list_item(f"{collector.collection} "
f"(previously included version: {collection_version})")
builder.add_raw_rst('')
for section in ['removed_features', 'deprecated_features']:
append_porting_guide_section(builder, changelog_entry, maybe_add_title, section)
def create_title_adder(builder: RstBuilder, title: str,
level: int) -> t.Generator[None, None, None]:
builder.add_section(title, level)
while True:
yield
