Migrating from BundleWrap 2.x to 3.x

As per semver, BundleWrap 3.0 breaks compatibility with repositories created for BundleWrap 2.x. This document provides a guide on how to upgrade your repositories to BundleWrap 3.x. Please read the entire document before proceeding.


metadata.py

BundleWrap 2.x simply used all functions in metadata.py whose names don't start with an underscore as metadata processors. This led to awkward imports like from foo import bar as _bar. BundleWrap 3.x requires a decorator for explicitly designating functions as metadata processors:

@metadata_processor
def myproc(metadata):
    return metadata, DONE

You will have to add @metadata_processor to each metadata processor function. There is no need to import it; it is provided automatically, just like node and repo.

The accepted return values of metadata processors have changed as well. Metadata processors now always have to return a tuple with the first element being a dictionary of metadata and the remaining elements made up of various options to tell BundleWrap what to do with the dictionary. In most cases, you will want to return the DONE options as in the example above. There is no need to import options, they're always available.

When you previously returned metadata, False from a metadata processor, you will now have to return metadata, RUN_ME_AGAIN. For a more detailed description of the available options, see the documentation.


File and directory ownership defaults

Files, directories, and symlinks now have default values for the ownership and mode attributes. Previously the default was to ignore them. It's very likely that you won't have to do anything here, just be aware.


systemd services enabled by default

Again, just be aware, it's probably what you intended anyway.


Environment variables

The following env vars have been renamed (though the new names have already been available for a while, so chances are you're already using them):

OldNew
BWADDHOSTKEYSBW_ADD_HOST_KEYS
BWCOLORSBW_COLORS
BWITEMWORKERSBW_ITEM_WORKERS
BWNODEWORKERSBW_NODE_WORKERS


Item.display_keys and Item.display_dicts

If you've written your own items and used the display_keys() or display_dicts() methods or the BLOCK_CONCURRENT attribute, you will have to update them to the new API.