def _get_changelog_bytes(changelog: Changelog) -> bytes:
builder = RstBuilder()
if changelog.ansible_version.major > 2:
version = f"{changelog.ansible_version.major}"
else:
version = f"{changelog.ansible_version.major}.{changelog.ansible_version.minor}"
builder.set_title(f"Ansible {version} Release Notes")
if changelog.ansible_ancestor_version:
builder.add_raw_rst(
f"This changelog describes changes since"
f" Ansible {changelog.ansible_ancestor_version}.\n")
builder.add_raw_rst('.. contents::\n :local:\n :depth: 2\n')
entries = [
entry for entry in changelog.entries if not entry.is_ancestor
]
for index, changelog_entry in enumerate(entries):
append_changelog(builder,
changelog.collection_metadata,
changelog_entry,
is_last=index + 1 == len(entries))
return builder.generate().encode('utf-8')
def _get_porting_guide_bytes(changelog: Changelog) -> bytes:
builder = RstBuilder()
builder.add_raw_rst(
f"..\n"
f" THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT"
f" MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_base_"
f"{changelog.ansible_version.major}.{changelog.ansible_version.minor}.rst)\n"
)
builder.add_raw_rst(f".. _porting_{changelog.ansible_version.major}."
f"{changelog.ansible_version.minor}_guide:\n")
builder.set_title(
f"Ansible {changelog.ansible_version.major}.{changelog.ansible_version.minor}"
f" Porting Guide")
builder.add_raw_rst(
# noqa: E501
".. warning::"
"\n\n"
" "
" In Ansible 2.10, many plugins and modules have migrated to"
" Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. Your playbooks"
" should continue to work without any changes. We recommend you start using the"
" fully-qualified collection name (FQCN) in your playbooks as the explicit and"
" authoritative indicator of which collection to use as some collections may contain"
" duplicate module names."
"\n\n"
"This section discusses the behavioral changes between Ansible 2.9 and Ansible 2.10."
"\n\n"
"It is intended to assist in updating your playbooks, plugins and other parts of"
" your Ansible infrastructure so they will work with this version of Ansible."
"\n\n"
"We suggest you read this page along with the `Ansible Changelog for 2.10 <https://"
"github.com/ansible-community/ansible-build-data/blob/main/2.10/CHANGELOG-v2.10.rst>`_"
" to understand what updates you may need to make."
"\n\n"
"Since 2.10, Ansible consists of two parts:\n\n"
"* ansible-base, which includes the command line tools with a small selection"
" of plugins and modules, and\n"
"* a `set of collections <https://github.com/ansible-community/ansible-build-data/"
"blob/main/2.10/ansible.in>`_."
"\n\n"
"The :ref:`porting_2.10_guide_base` is included in this porting guide. The complete"
" list of porting guides can be found at :ref:`porting guides <porting_guides>`."
"\n")
builder.add_raw_rst('.. contents::\n :local:\n :depth: 2\n')
base_porting_guide = changelog.base_collector.porting_guide
if base_porting_guide:
lines = base_porting_guide.decode('utf-8').splitlines()
lines.append('')
found_topics = False
found_empty = False
for line in lines:
if not found_topics:
if line.startswith('.. contents::'):
found_topics = True
continue
if not found_empty:
if line == '':
found_empty = True
continue
builder.add_raw_rst(line)
if not found_empty:
print(
'WARNING: cannot find TOC of ansible-base porting guide!')
for porting_guide_entry in changelog.entries:
append_porting_guide(builder, porting_guide_entry)
return builder.generate().encode('utf-8')
def _get_porting_guide_bytes(changelog: Changelog) -> bytes:
if changelog.ansible_version.major > 2:
version = f"{changelog.ansible_version.major}"
base_version = changelog.base_collector.latest
base_version = f"{base_version.major}.{base_version.minor}"
else:
version = f"{changelog.ansible_version.major}.{changelog.ansible_version.minor}"
base_version = f"{changelog.ansible_version.major}.{changelog.ansible_version.minor}"
builder = RstBuilder()
builder.add_raw_rst(
f"..\n"
f" THIS DOCUMENT IS AUTOMATICALLY GENERATED BY ANTSIBULL! PLEASE DO NOT EDIT"
f" MANUALLY! (YOU PROBABLY WANT TO EDIT porting_guide_base_{base_version}.rst)\n"
)
builder.add_raw_rst(f".. _porting_{version}_guide:\n")
builder.set_title(f"Ansible {version} Porting Guide")
if changelog.ansible_version.major == 2:
builder.add_raw_rst(
# noqa: E501
".. warning::"
"\n\n"
" "
" In Ansible 2.10, many plugins and modules have migrated to"
" Collections on `Ansible Galaxy <https://galaxy.ansible.com>`_. Your playbooks"
" should continue to work without any changes. We recommend you start using the"
" fully-qualified collection name (FQCN) in your playbooks as the explicit and"
" authoritative indicator of which collection to use as some collections may"
" contain duplicate module names."
" You can search the `index of all modules"
" <https://docs.ansible.com/ansible/2.10/collections/index_module.html>`_"
" to find the collection a module has been relocated to."
"\n\n"
"This section discusses the behavioral changes between Ansible 2.9 and"
" Ansible 2.10."
"\n\n"
"It is intended to assist in updating your playbooks, plugins and other parts of"
" your Ansible infrastructure so they will work with this version of Ansible."
"\n\n"
"We suggest you read this page along with the `Ansible 2.10 Changelog <https://"
"github.com/ansible-community/ansible-build-data/blob/main/2.10/"
"CHANGELOG-v2.10.rst>`_"
" to understand what updates you may need to make."
"\n\n"
"Since 2.10, Ansible consists of two parts:\n\n"
"* ansible-base, which includes the command line tools with a small selection"
" of plugins and modules, and\n"
"* a `set of collections <https://github.com/ansible-community/ansible-build-data/"
"blob/main/2.10/ansible.in>`_."
"\n\n"
"The :ref:`porting_2.10_guide_base` is included in this porting guide. The complete"
" list of porting guides can be found at :ref:`porting guides <porting_guides>`."
"\n")
builder.add_raw_rst('.. contents::\n :local:\n :depth: 2\n')
# Determine ansible-base/-core version in previous major release
prev_base_version = ''
if any(entry.is_ancestor for entry in changelog.entries):
# If there is an ancestor, the earliest ansible-base/-core version will be the
# version used in the previous major release.
prev_base_version = changelog.base_collector.earliest
prev_base_version = f"{prev_base_version.major}.{prev_base_version.minor}"
# Determine whether to include ansible-base/-core porting guide or not
if changelog.ansible_version.major == 2 or base_version != prev_base_version:
builder.add_raw_rst(
# noqa: E501
"\n"
f"We suggest you read this page along with the `Ansible {version} Changelog"
f" <https://github.com/ansible-community/ansible-build-data/blob/main/{version}/"
f"CHANGELOG-v{version}.rst>`_ to understand what updates you may need to make."
"\n")
ReleaseNotes._append_base_porting_guide_bytes(builder, changelog)
elif changelog.ansible_version.major == 3:
# Special message for Ansible 3
builder.add_raw_rst(
# noqa: E501
"\n"
"Ansible 3 is based on Ansible-Base 2.10, which is the same major release as"
" Ansible 2.10. Therefore, there is no section on ansible-base in this porting"
" guide. If you are upgrading from Ansible 2.9, please first consult the"
" Ansible 2.10 porting guide before continuing with the Ansible 3 porting guide."
"\n\n"
"We suggest you read this page along with the `Ansible 3 Changelog"
" <https://github.com/ansible-community/ansible-build-data/blob/main/3/"
"CHANGELOG-v3.rst>`_ to understand what updates you may need to make."
"\n")
else:
# Generic message if we again have two consecutive versions with the same ansible-core
prev_version = changelog.ansible_version.major - 1
prev_prev_version = changelog.ansible_version.major - 2
builder.add_raw_rst(
# noqa: E501
"\n"
f"Ansible {version} is based on Ansible-core {base_version}, which is the same"
f" major release as Ansible {prev_version}. Therefore, there is no section on"
" ansible-core in this porting guide. If you are upgrading from Ansible"
f" {prev_prev_version}, please first consult the Ansible {prev_version} porting"
f" guide before continuing with the Ansible {version} porting guide."
"\n\n"
f"We suggest you read this page along with the `Ansible {version} Changelog"
f" <https://github.com/ansible-community/ansible-build-data/blob/main/{version}/"
f"CHANGELOG-v{version}.rst>`_ to understand what updates you may need to make."
"\n")
for porting_guide_entry in changelog.entries:
if not porting_guide_entry.is_ancestor:
append_porting_guide(builder, porting_guide_entry)
return builder.generate().encode('utf-8')
