Adding core plugins
This is a checklist of things which need to be done when adding a new core plugin to BuildStream proper.
Update documentation index
The documentation generating scripts will automatically pick up your newly added plugin and generate HTML, but will not add a link to the documentation of your plugin automatically.
Whenever adding a new plugin, you must add an entry for it in
Needless to say, all new feature additions need to be tested. For
plugins, these usually need to be added to the integration tests. For
plugins, the tests are added in two ways:
For most normal
Sourceplugins, it is important to add a new
Repoimplementation for your plugin in the
tests/testutils/repo/directory and update
tests/testutils/repo/__init__.py. This will include your new
Sourceimplementation in a series of already existing tests, ensuring it works well under normal operating conditions.
For other source plugins, or in order to test edge cases, such as failure modes, which are not tested under the normal test battery, add new tests in
Extend the cachekey test
For any newly added plugins, it is important to add some new simple elements
and ensure that the newly added elements are depended on by
One new element should be added to the cache key test for every configuration
value which your plugin understands which can possibly affect the result of
This test ensures that cache keys do not unexpectedly change or become incompatible due to code changes. As such, the cache key test should have full coverage of every YAML configuration which can possibly affect cache key outcome at all times.
src/buildstream/testing/_update_cachekeys.py file for instructions on running the updater,
you need to run the updater to generate the
.expected files and add the new
.expected files in the same commit which extends the cache key test.