Skip to content

Plugins

Looking for?

  • The design principles behind plugins, check guide.
  • A complete reference for plugins classes, App, Tracker, Host and Submiter, check the SDK.
  • How to create a plugin, check the guide.
  • How to manage plugins in your instance, check the TD documentation.

Warning

This documentation assumes that you have already set up a Bip development instance, and that your development directories are following the recommended structure.

Introduction

This guide shows how to set up your development environment for working on a plugin.

By default, a plugin is initialized by:

  • The sdk.runner for applications.
  • The mink.plugins getter methods for handlers.

In both cases, the App or Handler object initialized is loaded with a Plugin object (link.plugin) from the database. This is the way designed in Bip for the App or Handler instance to be loaded with the plugin configuration, user setting and mapping values defined by the user and the administrator of the Bip instance.

But when developing a plugin, you don't want to register the plugin source to the database, and enable a locked version of that plugin. You want to be able to modify the bip.yml descriptor any-time, without reflecting those changes of the database.

This is why the BIP_DEBUG_PLUGIN environment variable has been created. When set with the path(s) to the root directory of the plugin(s) you are working on, this variable tells Bip to initialize the plugin object with a fake floating Plugin object generated temporally from the repository descriptor instead of trying to find it on the database. same for the user settings. Some fake default user settings are generated on the fly.

Info

If your plugin uses other plugins as dependencies, it is strongly recommended to always work with all the plugins in development mode, which means concretely that you should have all the dependency plugins cloned locally and added to your plugin project in your favourite IDE.

Code

Create and populate the minimal working structure for your plugin: descriptor bip.yml and entry point handler.py if the plugin is a handler.

Tip

If the plugin is an application, you can use the demo application Chocolatine as a base template.

Test

Standalone

When running your plugin, specify the following environment variables:

  • BIP_DEBUG_PLUGIN: Get the plugin data from the working project instead of the database (example: /path/to/my/plugin;path/to/another/plugin)
  • BIP_CONFIG: Bip configuration file (example: /path/to/bip/config/config.yml)
  • BIP_AUTH: Bip authentication file (example: /path/to/bip/config/auth.yml)
  • BIP_DATABASE_PASSWORD: Neo4j password (example: your-database-password)
  • BIP_CONTENT: Bip content repository (example: /path/to/bip/content)

Optionally, you can also specify BIP_DEBUG_PLUGIN_DATA in order to provide values to the mapping and/or config parameters. The environment variable value should be a path to a yaml file containing the values for each parameter you want to set. The file should be structure like so:

plugin-slug:
  config:
    param1: Hello world
    param2: 123
  mapping:
    mapping1: asset
    mapping2: shot

If your development machine has a production Bip client installed, you must also override the following environment variables, in order to avoid conflicting with the production instance:

  • BIP_PATH: Root of the Bip ecosystem (example: path/to/the/parent/folder/of/your/bip/repo)
  • BIP_PYTHON: Python virtual environment (example: path/to/the/root/of/the/python_venv)

Hosted

If you are developing a Host plugin or an application which accepts the HOSTED context, you need to use a Python 3.9 virtual environment with the Bip client dependencies installed on. It won't be used for its interpreter, but for its site-packages folder.

You can use the following hacky script for running your plugin from the DCC interpreter without having to restart the DCC.

Warning

Deleting modules that way is not recommended and can lead to buggy behaviours. Keep that in mind while debugging.

import os
import sys

# Change these:
PYTHON = "path/to/host/venv/Lib/site-packages"
BIP_ROOT = "path/to/bip"
BIP_CONFIG = "path/to/config.yml"
BIP_AUTH = "path/to/auth.yml"
BIP_PASSWORD = "it-is-a-secret"


def set_environment():
    def __delete_modules(starts_with):
        to_delete = [m for m in sys.modules if m.startswith(starts_with)]
        for module in to_delete:
            if module in sys.modules:
                del sys.modules[module]

    __delete_modules(starts_with="bip")
    __delete_modules(starts_with="my_app")
    __delete_modules(starts_with="my_host_handler")

    # Environment variables
    os.environ["BIP_CONFIG"] = BIP_CONFIG
    os.environ["BIP_ROOT"] = BIP_ROOT + "/client"
    os.environ["BIP_DATABASE_PASSWORD"] = BIP_PASSWORD
    os.environ["BIP_AUTH"] = BIP_AUTH
    os.environ["BIP_DEBUG_PLUGIN"] = BIP_ROOT + "/apps/my_app" + ";" + BIP_ROOT + "/handlers/my_host_handler"

    # Python path
    sys.path.append(PYTHON)
    sys.path.append(BIP_ROOT + "/client")
    sys.path.append(BIP_ROOT + "/apps/my_app")
    sys.path.append(BIP_ROOT + "/handlers/my_host_handler")


def run_app():
    import my_app.my_entry_point
    my_app.my_entry_point.do_something()


set_environment()
run_app()

Publish

When your plugin is ready for a new version, you must do the following:

  • Update the changelog
  • Update the version number
  • Create a Git tag
  • Create a Git release (optional)
  • Upgrade the plugin on Bip instances (bonus)

Changelog

Warning

The changelog is parsed by bip.mink.changelog for it to be displayed nicely in UI. Therefore, it must be strictly formatted according the guidelines.

Add a new h2 heading named [X.X.X] - YYYY/MM/DD.

Add h3 headings for Added, Changed, Fixed, Removed when necessary, and describe in a user-friendly way the changes.

Add an url corresponding to that new version's compare view. It usually looks like https://gitlab.com/someone/something/-/compare/v2.0.5...v2.1.0

Edit the [unreleased] url with the next compare view, so it compares the version you are about to create with the repository head. It usually looks like `https://gitlab.com/someone/something/-/compare/v2.1.0...main

Example

Have a look at this commit example from a Savarin update from v0.0.3 to v0.0.4.

Version number

Warning

The version number must follow the Semantic Versioning convention.

Update the version field in pyproject.toml with the new version umber.

Example

Have a look at this commit example from a Savarin update from v0.0.3 to v0.0.4.

Tag

Warning

Bip plugin API is using the Git tags for its updating mechanism. They must be named X.X.X orvX.X.X.

Create a new Git tag (either on your local repository and then push it, or on your remote repository, after having pushed your modification).

Tip

If you are using Gitlab, you can create the tag and the release all at once. See the next release section.

You should use a tag message to avoid creating a lightweight tag. If lazy, just type Major, Minor or Patch depending on the type of version.

Release

Optionally, you can also create a release, embedding the changelog of the version, on your codebase tracker. It is a good development practice to do so.

Gitlab

Go to your project's Releases tab, anc click on New release.

Select the tag.

Tip

You can directly create the tag from here, by typing the name of the new tag.

In the release notes, copy and past the version release notes from your CHANGELOG.md. You only need to copy and past the h3 levels (Added, Changed, Fixed, Removed).

Click on Create release.

The plugin new version is officially published.

Upgrade

If you are also administrating one or several Bip instances where your plugin is enabled, you might want to perform the upgrade at the same time.

This can be done by script or with Clafoutis.