Merge pull request #411 from plone/MrTango/add-upgrate-step-template

Mr tango/add upgrate step template

CHANGES.rst

@@ -1,10 +1,11 @@
 Changelog
 =========
 
-4.1.5 (unreleased)
+5.0.0 (2019-10-18)
 ------------------
 
-- Nothing changed yet.
+- Add upgrade_step sub-template, remove upgrades from addon template, read the `Upgrade chapter <https://bobtemplatesplone.readthedocs.io/en/latest/upgrade-packages.html>`_ in the docs, how to upgrade existing packages.
+  [MrTango]
 
 
 4.1.4 (2019-10-18)

bobtemplates/plone/addon/src/+package.namespace+/+package.name+/configure.zcml.bob

@@ -17,8 +17,6 @@
 
   <include file="permissions.zcml" />
 
-  <include file="upgrades.zcml" />
-
   <genericsetup:registerProfile
       name="default"
       title="{{{ package.dottedname }}}"

bobtemplates/plone/upgrade_step.py

@@ -0,0 +1,102 @@
+# -*- coding: utf-8 -*-
+
+from bobtemplates.plone.base import base_prepare_renderer
+from bobtemplates.plone.base import git_commit
+from bobtemplates.plone.base import remove_unwanted_files
+from bobtemplates.plone.base import update_configure_zcml
+from lxml import etree
+
+
+def _update_package_configure_zcml(configurator):
+    path = '{0}'.format(
+        configurator.variables['package_folder'],
+    )
+    file_name = u'configure.zcml'
+    match_xpath = "zope:include[@package='.upgrades']"
+    match_str = '-*- extra stuff goes here -*-'
+    insert_str = """
+  <include package=".upgrades" />
+"""
+    update_configure_zcml(
+        configurator,
+        path,
+        file_name=file_name,
+        match_xpath=match_xpath,
+        match_str=match_str,
+        insert_str=insert_str,
+    )
+
+
+def _update_upgrades_configure_zcml(configurator):
+    path = '{0}/upgrades'.format(
+        configurator.variables['package_folder'],
+    )
+    file_name = u'configure.zcml'
+    example_file_name = '{0}.example'.format(file_name)
+    zcml_package_name = configurator.variables['upgrade_step_dest_version']
+    match_xpath = "zope:include[@package='.{0}']".format(zcml_package_name)
+    match_str = '-*- extra stuff goes here -*-'
+    insert_str = """
+  <include package=".{0}" />
+""".format(zcml_package_name)
+    update_configure_zcml(
+        configurator,
+        path,
+        file_name=file_name,
+        example_file_name=example_file_name,
+        match_xpath=match_xpath,
+        match_str=match_str,
+        insert_str=insert_str,
+    )
+
+
+def _remove_unwanted_files(configurator):
+    file_paths = []
+    rel_file_paths = [
+        '/upgrades/configure.zcml.example',
+    ]
+    base_path = configurator.variables['package_folder']
+    for rel_file_path in rel_file_paths:
+        file_paths.append('{0}{1}'.format(base_path, rel_file_path))
+    remove_unwanted_files(file_paths)
+
+
+def _read_source_version(configurator):
+    base_path = configurator.variables['package_folder']
+    rel_file_path = '/profiles/default/metadata.xml'
+    metadata_path = '{0}{1}'.format(base_path, rel_file_path)
+    with open(metadata_path, 'r') as xml_file:
+        parser = etree.XMLParser(remove_blank_text=True)
+        tree = etree.parse(xml_file, parser)
+        tree_root = tree.getroot()
+        match_xpath = "version"
+        match_result = tree_root.findall(match_xpath)
+        if not match_result:
+            raise RuntimeError("source version not found in metadata.xml!")
+            return
+        return int(match_result[0].text)
+
+
+def pre_renderer(configurator):
+    """Pre rendering."""
+    configurator = base_prepare_renderer(configurator)
+    configurator.variables['template_id'] = 'upgrade_step'
+    upgrade_step_source_version = _read_source_version(configurator)
+    upgrade_step_dest_version = upgrade_step_source_version + 1
+    configurator.variables['upgrade_step_source_version'] = upgrade_step_source_version
+    configurator.variables['upgrade_step_dest_version'] = upgrade_step_dest_version
+    configurator.variables['upgrade_step_id'] = str(upgrade_step_dest_version)
+    configurator.target_directory = configurator.variables['package_folder']
+
+
+def post_renderer(configurator):
+    """Post rendering."""
+    _update_package_configure_zcml(configurator)
+    _update_upgrades_configure_zcml(configurator)
+    _remove_unwanted_files(configurator)
+    git_commit(
+        configurator,
+        'Add upgrade_step: {0}'.format(
+            configurator.variables['upgrade_step_title'],
+        ),
+    )

bobtemplates/plone/upgrade_step/.mrbob.ini

@@ -0,0 +1,23 @@
+[questions]
+subtemplate_warning.question = Please commit your changes, before using a sub-template! Continue anyway? [n/y]
+subtemplate_warning.required = True
+subtemplate_warning.default = n
+subtemplate_warning.pre_ask_question = bobtemplates.plone.base:git_clean_state_check
+subtemplate_warning.post_ask_question = mrbob.hooks:validate_choices bobtemplates.plone.base:subtemplate_warning_post_question
+subtemplate_warning.choices = y|n
+subtemplate_warning.choices_delimiter = |
+
+upgrade_step_title.question = Upgrade step title
+upgrade_step_title.help = Give your upgrade step a meaningful title.
+upgrade_step_title.default =
+upgrade_step_title.required = True
+
+upgrade_step_description.question = Upgrade step description
+upgrade_step_description.help = Give your upgrade step a meaningful description.
+upgrade_step_description.default =
+upgrade_step_description.required = False
+
+[template]
+post_ask = bobtemplates.plone.base:set_global_vars
+pre_render = bobtemplates.plone.upgrade_step:pre_renderer
+post_render = bobtemplates.plone.upgrade_step:post_renderer

bobtemplates/plone/upgrade_step/tests/test_upgrade_step_+upgrade_step_id+.py.bob

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+from plone.app.testing import setRoles
+from plone.app.testing import TEST_USER_ID
+from {{{package.dottedname}}}.testing import {{{package.uppercasename}}}_FUNCTIONAL_TESTING
+from {{{package.dottedname}}}.testing import {{{package.uppercasename}}}_INTEGRATION_TESTING
+
+import unittest
+
+
+class UpgradeStepIntegrationTest(unittest.TestCase):
+
+    layer = {{{package.uppercasename}}}_INTEGRATION_TESTING
+
+    def setUp(self):
+        self.portal = self.layer['portal']
+        setRoles(self.portal, TEST_USER_ID, ['Manager'])
+
+
+class UpgradeStepFunctionalTest(unittest.TestCase):
+
+    layer = {{{package.uppercasename}}}_FUNCTIONAL_TESTING
+
+    def setUp(self):
+        self.portal = self.layer['portal']
+        setRoles(self.portal, TEST_USER_ID, ['Manager'])

bobtemplates/plone/upgrade_step/upgrades/+upgrade_step_id+.zcml.bob

@@ -0,0 +1,24 @@
+<configure xmlns="http://namespaces.zope.org/zope"
+  xmlns:gs="http://namespaces.zope.org/genericsetup">
+
+  <gs:registerProfile name="{{{ upgrade_step_dest_version }}}"
+    title="{{{ upgrade_step_title }}}"
+    description='Configuration for version {{{ upgrade_step_dest_version }}}'
+    for="Products.CMFPlone.interfaces.IMigratingPloneSiteRoot"
+    provides="Products.GenericSetup.interfaces.EXTENSION" />
+
+  <gs:upgradeSteps source="{{{ upgrade_step_source_version }}}"
+    destination="{{{ upgrade_step_dest_version }}}"
+    profile="{{{ package.dottedname }}}:default">
+
+    <gs:upgradeStep title="{{{ upgrade_step_title }}}"
+      description="{{{ upgrade_step_description }}}"
+      handler=".v{{{ upgrade_step_dest_version }}}.upgrade" />
+
+    <gs:upgradeDepends title="{{{ upgrade_step_title }}} (GS profile)"
+      description="{{{ upgrade_step_description }}}"
+      import_profile="{{{ package.dottedname }}}.upgrades:{{{ upgrade_step_dest_version }}}" />
+
+  </gs:upgradeSteps
+
+</configure>

bobtemplates/plone/addon/src/+package.namespace+/+package.name+/upgrades.py.bob → bobtemplates/plone/upgrade_step/upgrades/base.py

@@ -5,5 +5,5 @@
 def reload_gs_profile(context):
     loadMigrationProfile(
         context,
-        'profile-{{{ package.dottedname }}}:default',
+        "profile-{{{ package.dottedname }}}:default",
     )

bobtemplates/plone/upgrade_step/upgrades/configure.zcml.example.bob

@@ -0,0 +1,7 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    i18n_domain="{{{ package.dottedname }}}">
+
+  -*- extra stuff goes here -*-
+
+</configure>

bobtemplates/plone/upgrade_step/upgrades/v+upgrade_step_id+.py.bob

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+
+from . import logger
+
+
+def upgrade(setup_tool=None):
+    """
+    """
+    logger.info("Running upgrade (Python): {{{ upgrade_step_title }}}")

docs/upgrade-packages.rst

@@ -8,15 +8,33 @@ bobtemplate.cfg
 To upgrade an existing Plone package, to work with the new sub-templates and also the plonecli. You simply need to add a bobtemplate.cfg with some content like this::
 
     [main]
-    version = 5.1
+    version = 5.2
     template = plone_addon
+    python = python3.7
 
 The version is used to make a difference in some templates, either for Plone 5 or Plone 4 packages. You can always create an addon package with the plonecli and copy over the bobtemplate.cfg in your old package.
 
-requiremens.txt
-===============
+other files
+===========
+
+You should have at leased a requirements.txt and a buildout.cfg file.
+But it's recommended to add the following files from a generated addon package into your existing package:
+
+- requirements.txt
+- constraints.txt
+- constraints_plone52.txt
+- constraints_plone51.txt
+- test_plone52.cfg
+- test_plone51.cfg
+- tox.ini
+
+Folder structure
+================
+
+Since this package expects a specific folder structure, you should compare it to your existing structure and adjust it, where needed.
 
-In case you don't have a ``requirements.txt`` already in your package repository, you should also add this::
+Upgrade steps
+=============
 
-    setuptools==38.2.4
-    zc.buildout==2.10.0
+The upgrade_step sub-template uses an upgrades folder to create upgrade steps in it. Therefor you should adjust existing upgrade step configuration to it.
+You can have a look at `Products.EasyNewsletter <https://github.com/collective/Products.EasyNewsletter/tree/master/src/Products/EasyNewsletter>`_ where this was done.