Grow 1.0.0 migration

The 1.0.0 release for Grow marks the switch from Python 2.7 to Python 3. This migration guide highlights some of the changes that the switch brings and required changes to be able to use the latest grow.

Python 3

The single biggest change is Grow is now only supporting Python 3.7+. In order to use the latest Grow make sure that you have Python 3 installed.

You can test if you have Python 3 installed by running python3 --version in the terminal.

Python 3 is provided with the latest version of macOS. If you need to manually install it, or if you are locked to another version of macOS, you can use pyenv)

Grow packaged app -> Pipenv

On previous versions of Grow we offered a 'packaged' version of Grow as a downloadable binary. With the change to Python 3 we have replaced the packaged version of Grow with the usage of Pipenv. This change allows for individual projects to easily run different versions of Grow and provides a consistent way to install and update Grow.

Please follow the Pipenv instructions for installing Pipenv.

You can test if you have Pipenv installed by running pipenv --version

Once you have Pipenv installed, you can create the Pipenv configuration by running the following in your project directory:

# Create a Pipenv environment using Python 3 and install Grow.
pipenv --python 3
pipenv install grow

Pipenv will create a Pipfile and Pipfile.lock that contain the configuration for Pipenv. These files should be added to your repository.

After the initial Pipfile is added to the repository, update the readme and/or other documentation to show updated instructions for installing and using Grow.

# Setup pipenv environment and install dependencies.
pipenv install

After the Pipenv installation is complete you can run grow commands:

pipenv run grow install
pipenv run grow build
pipenv run grow run
# etc.

Tip: If you are only using Grow on projects that use Grow >=1.0.0 you can add a grow alias to your sh profile to shorten the command:

alias grow=pipenv run grow

Full install instructions are available from the install page.

Breaking changes

Dropped support for old style formatting

Previously deprecated, the support for using old style python formatting in gettext(), _(), and translations is removed. Instead use the newer python format style.

# OLD
Hey %(name)s

# NEW
Hey {name}

Extension Python 3 changes

Extensions may break when using Python 3. Please check that you are using the latest versions of the extension in the extensions.txt file and update any custom extensions to support Python 3.

You can try using the 2to3 conversion utility to convert old extensions over to Python 3.

If you have questions on converting extensions over to Python 3 you can ask for help on the Grow Google Group.

Docker image updates

Previous versions of Grow were pinned to use Node 8 which is currently past the end-of-life.

From 1.0.0 onwards the grow/base docker images will use the LTS version of Node. This can cause issues as node dependencies will need to be updated to support whatever the current LTS version of Node is.

LTS versions of Node update about once a year around April according to the current Node release schedule.

As a result, if your project uses the grow/base Docker images, you will need to ensure that any project Node dependencies are also upgraded. Typically, this means that you'll need to upgrade older Gulp installations to use Gulp 4 or newer.

Deprecations

Legacy extensions

There is a relatively new way to create extensions. Extensions using the older extension format will still be supported, but in the long term extensions should be converted to use the new format as support for older extensions will be dropped in the future.

When running Grow 1.0.0+ you may see a message similar to this:

Legacy preprocessors are deprecated and will be removed in the future: google_sheets

Please check with the individual extensions to see if they have an open issue for converting over to the newer extension format.

For example, The google-cloud-images extension has an issue open to track the conversion to the newer extension style.

If you have questions on converting extensions over to the newer style you can ask for help on the Grow Google group.