Add a script to generate a new porting guide

* porting-guide.py is allowed to be Python-3.6+ as it will only be run
  by release engineers

docs/docsite/rst/porting_guides/porting_guide_2.9.rst

@@ -0,0 +1,78 @@
+
+.. _porting_2.9_guide:
+
+*************************
+Ansible 2.9 Porting Guide
+*************************
+
+This section discusses the behavioral changes between Ansible 2.8 and Ansible 2.9.
+
+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.
+
+We suggest you read this page along with `Ansible Changelog for 2.9 <https://github.com/ansible/ansible/blob/devel/changelogs/CHANGELOG-v2.9.rst>`_ to understand what updates you may need to make.
+
+This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
+
+.. contents:: Topics
+
+
+Playbook
+========
+
+No notable changes
+
+
+Command Line
+============
+
+No notable changes
+
+
+Deprecated
+==========
+
+No notable changes
+
+
+Modules
+=======
+
+No notable changes
+
+
+Modules removed
+---------------
+
+The following modules no longer exist:
+
+* No notable changes
+
+
+Deprecation notices
+-------------------
+
+No notable changes
+
+
+Noteworthy module changes
+-------------------------
+
+No notable changes
+
+
+Plugins
+=======
+
+No notable changes
+
+
+Porting custom scripts
+======================
+
+No notable changes
+
+
+Networking
+==========
+
+No notable changes

hacking/porting-guide.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+# coding: utf-8
+# Copyright: (c) 2019, Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+# Make coding more python3-ish
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+import argparse
+import sys
+
+from jinja2 import Environment, DictLoader
+
+
+PORTING_GUIDE_TEMPLATE = """
+.. _porting_{{ ver }}_guide:
+
+*************************
+Ansible {{ ver }} Porting Guide
+*************************
+
+This section discusses the behavioral changes between Ansible {{ prev_ver }} and Ansible {{ ver }}.
+
+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.
+
+We suggest you read this page along with `Ansible Changelog for {{ ver }} <https://github.com/ansible/ansible/blob/devel/changelogs/CHANGELOG-v{{ ver }}.rst>`_ to understand what updates you may need to make.
+
+This document is part of a collection on porting. The complete list of porting guides can be found at :ref:`porting guides <porting_guides>`.
+
+.. contents:: Topics
+
+
+Playbook
+========
+
+No notable changes
+
+
+Command Line
+============
+
+No notable changes
+
+
+Deprecated
+==========
+
+No notable changes
+
+
+Modules
+=======
+
+No notable changes
+
+
+Modules removed
+---------------
+
+The following modules no longer exist:
+
+* No notable changes
+
+
+Deprecation notices
+-------------------
+
+No notable changes
+
+
+Noteworthy module changes
+-------------------------
+
+No notable changes
+
+
+Plugins
+=======
+
+No notable changes
+
+
+Porting custom scripts
+======================
+
+No notable changes
+
+
+Networking
+==========
+
+No notable changes
+
+"""  # noqa for E501 (line length).
+# jinja2 is horrid about getting rid of extra newlines so we have to have a single line per
+# paragraph for proper wrapping to occur
+
+JINJA_ENV = Environment(
+    loader=DictLoader({'porting_guide': PORTING_GUIDE_TEMPLATE,
+                       }),
+    extensions=['jinja2.ext.i18n'],
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+
+
+def parse_args(args):
+    parser = argparse.ArgumentParser(description="Generate a fresh porting guide template")
+    parser.add_argument("--version", dest="version", type=str, required=True, action='store',
+                        help="Version of Ansible to write the porting guide for")
+
+    args = parser.parse_args(args)
+
+    return args
+
+
+def generate_porting_guide(version):
+    template = JINJA_ENV.get_template('porting_guide')
+
+    version_list = version.split('.')
+    version_list[-1] = str(int(version_list[-1]) - 1)
+    previous_version = '.'.join(version_list)
+
+    content = template.render(ver=version, prev_ver=previous_version)
+    return content
+
+
+def write_guide(version, guide_content):
+    filename = f'porting_guide_{version}.rst'
+    with open(filename, 'w') as out_file:
+        out_file.write(guide_content)
+
+
+def main():
+    args = parse_args(sys.argv[1:])
+
+    guide_content = generate_porting_guide(args.version)
+
+    write_guide(args.version, guide_content)
+
+
+if __name__ == '__main__':
+    main()

test/sanity/code-smell/shebang.py

@@ -38,8 +38,9 @@ def main():
         'test/integration/targets/win_module_utils/library/legacy_only_old_way_win_line_ending.ps1',
         'test/utils/shippable/timing.py',
         'test/integration/targets/old_style_modules_posix/library/helloworld.sh',
-        # Python 3-only.  Only run by release engineers
+        # The following are Python 3.6+.  Only run by release engineers
         'hacking/release-announcement.py',
+        'hacking/porting-guide.py',
     ])
 
     # see https://unicode.org/faq/utf_bom.html#bom1

test/sanity/compile/python2.6-skip.txt

@@ -1,2 +1,3 @@
-# Only run by release engineers who can be asked to have newer Python3 on their systems
+# The following are only run by release engineers who can be asked to have newer Python3 on their systems
 hacking/release-announcement.py
+hacking/porting-guide.py

test/sanity/compile/python2.7-skip.txt

@@ -1,2 +1,3 @@
-# Only run by release engineers who can be asked to have newer Python3 on their systems
+# The following are only run by release engineers who can be asked to have newer Python3 on their systems
 hacking/release-announcement.py
+hacking/porting-guide.py

test/sanity/compile/python3.5-skip.txt

@@ -1,2 +1,3 @@
-# Only run by release engineers who can be asked to have newer Python3 on their systems
+# The following are only run by release engineers who can be asked to have newer Python3 on their systems
 hacking/release-announcement.py
+hacking/porting-guide.py