Distributing and versioning
There are three routes for bringing a plugin onto an instance. Which one you take depends on who maintains the plugin.
| Route | For whom | How |
|---|---|---|
| Committed | Plugins that belong to the system | Entry in the bundle list, namespace in the package file |
| Package manager | Plugins with a repository of their own | composer require |
| Package file | Delivery to customers without development access | Upload a ZIP or apply it by command |
Route A: committed
The route for everything that is maintained together with the system. Two entries, described in the quick start.
Route B: through the package manager
composer require acme/octibiz-shippingThe package carries the type octibiz-plugin. An installation helper recognises it and rewrites the bundle list. After that you install it like any other.
This route does not check the contract version. You are responsible yourself for your plugin matching the major line of the instance.
Route C: as a package file
zip -r ../AcmeShipping.zip .The manifest file has to sit at the root of the archive, not in a subfolder.
Apply it either through the interface or by command:
bin/console octibiz:plugin:install-package AcmeShipping.zipThe sequence is fixed and rolls back on every error: unpack, rebuild the container, run migrations, set up, and if there is an interface, rebuild it.
Checks run beforehand, all of them before the first side effect: the contract version, whether an address segment of the core is being claimed, whether the class name is already taken.
The archive is read strictly: size budget, number of entries, compression ratio, and paths that lead out of the target directory are rejected. Links inside the archive are neutralised.
There is no signature check. Whoever applies a package runs foreign code. That is a deliberate decision for the current deployment and not an oversight; treat packages accordingly.
Three version axes
They get confused regularly:
| Axis | What it describes |
|---|---|
| System version | The state of the platform |
| Plugin version | The state of your plugin |
| Contract version | The stability of the interfaces between the two |
A change to your plugin does not raise the system version. A break in the contract raises neither of the two.
Were it one number, it would say nothing: it would change because a typo was fixed in some module, and nobody could tell from it whether an update is worth it.
Your version stands in four places
Authoritative is the constant in the descriptor. The same number stands in both package files and in the top section of the changelog.
make bump TARGET=acme.shipping BUMP=minorThe command moves all four along. Without entries under "Unreleased" it aborts instead of producing a version without content.
The contract version
It stands in your manifest file and says which surface you built against.
The promise is: within one major line the stable surface stays backwards compatible. A break forces a new major version. What counts as stable is frozen and checked against a reference on every build.
The contract version is not an axis you maintain yourself. You only name it.
The marketplace
It does not exist yet. The interface for it is designed and present in the code, but every call ends with the note that it is not set up. There are no endpoints, no catalogue, no review of submitted plugins.
Whoever ships today takes one of the three routes above.
Developing standalone
Without access to the system sources the contract surface is available as two packages, one each for backend and interface. Both follow the contract axis.
{
"require-dev": { "octibiz/plugin-sdk": "~3.15.0" },
"devDependencies": { "@octibiz/plugin-sdk": "~3.15.0" }
}Development dependency only. At runtime the instance supplies the real classes; if the package sat there as well, every class would exist twice.
What is in the package: the base class, all contracts, the frozen event classes, the payload types, the manifest contract of the interface.
What is not: classes that appear in no frozen signature. Entities, API resources, repositories and the services behind them belong to the system, not to the contract. For integration tests against the running platform you need a development checkout.
Before shipping
- The generator leftovers are gone, especially the example resource
- All four version places agree
- The changelog names what has changed
- The contract version in the manifest matches the target instance
make gateis green