Skip to content

Fix plugin API documentation - #740

Merged
jkloetzke merged 15 commits into
BobBuildTool:masterfrom
jkloetzke:fix-plugin-api
Nov 14, 2026
Merged

jkloetzke merged 15 commits into
BobBuildTool:masterfrom
jkloetzke:fix-plugin-api

Conversation

@jkloetzke

Copy link
Copy Markdown
Member

No description provided.

Only keep what is actually needed for plugins. Remove classes that were
never documented for plugins.
Expose the information about the used interpreter of a step.
Document the SCM class and the subset of its methods that plugins may
use.
Give plugins access to the SCMs of a checkout step. Other steps return
an empty list.
Describe the arguments and return types of all methods that are part of
the plugin API. Fix some outdated or wrong descriptions along the way:

* The PluginSetting class docstring was not picked up because it was
  placed after the priority attribute.
* Step.jobServer() does not return a bool but the jobserver mode.
* Step.getWorkspacePath() referenced the non-existing getExecPath().
String functions require at least apiVersion 0.15. Both the example in
the manual and the override sample plugin declared 0.2 and would be
rejected when loaded.
State trackers and string functions are passed an Env object and not a
plain dict. The path-fmt sample plugin even relies on Env.substitute().
Document the subset that plugins may use and explain why the environment
cannot be iterated.
The example used PackageSet.queryTreePath() which is not part of the
plugin API. Use queryPackagePath() instead. The default query now
matches all root packages, as promised by the help text.
The manifest referenced releaseFormatter and developFormatter which are
not defined in the example.
The 'state' manifest key was not documented at all. Describe how state
trackers are registered and instantiated, where their name is used and
add an example.
The buildSteps, checkoutSteps and packageSteps kwargs are dictionary
views. They can be iterated but not indexed.
Plugins must not generate packages themselves. Commands are passed the
already generated package set instead.
Many methods return internal lists and dictionaries instead of copies.
Modifying them would corrupt the state of Bob.
The properties passed to PluginState.onEnter() and onFinish() belong to
the recipe and are shared by all of its packages. Modifying them leaks
into other packages and is not covered by the package cache. Only the
environment may be modified. Changes in onEnter() are inherited by the
dependencies while changes in onFinish() only affect the current
package.
@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 90.40%. Comparing base (88daed8) to head (6bdd424).

Files with missing lines Patch % Lines
pym/bob/input/package.py 50.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #740      +/-   ##
==========================================
- Coverage   90.41%   90.40%   -0.01%     
==========================================
  Files          59       59              
  Lines       17404    17404              
==========================================
- Hits        15735    15734       -1     
- Misses       1669     1670       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@jkloetzke
jkloetzke merged commit c1d4b7d into BobBuildTool:master Nov 14, 2026
10 of 11 checks passed
@jkloetzke
jkloetzke deleted the fix-plugin-api branch November 14, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant