buildstream/plugin.py, doc/source/projectconf.rst: Changed policy for core plugin format revisioning

The policy for format revisioning of core plugins maintained in BuildStream
now changes such that we revision all plugins under the same core format version.

This means that format extensions in plugins should be revisioned in
the global _versions.BST_FORMAT_VERSION along with the core format, this
simplifies parameterization of project.conf for usage of core plugins.

This did not really require any code support as our plugins have never
been revisioned before.

2 files changed, 11 insertions, 26 deletions

diff --git a/buildstream/plugin.py b/buildstream/plugin.py
index ea650fca2..06c903191 100644
--- a/buildstream/plugin.py
+++ b/buildstream/plugin.py
@@ -131,7 +131,7 @@ class Plugin():
     """The plugin's YAML format version
 
     This should be set to ``1`` the first time any new configuration
-    is understood by your :func:`~buildstream.plugin.Plugin.configure`
+    is understood by your :func:`Plugin.configure() <buildstream.plugin.Plugin.configure>`
     implementation and subsequently bumped every time your
     configuration is enhanced.
 
@@ -140,6 +140,10 @@ class Plugin():
        Plugins are expected to maintain backward compatibility
        in the format and configurations they expose. The versioning
        is intended to track availability of new features only.
+
+       For convenience, the format version for plugins maintained and
+       distributed with BuildStream are revisioned with BuildStream's
+       core format version :ref:`core format version <project_format_version>`.
     """
 
     def __init__(self, name, context, project, provenance, type_tag):
diff --git a/doc/source/projectconf.rst b/doc/source/projectconf.rst
index d740bb0e3..97d916f91 100644
--- a/doc/source/projectconf.rst
+++ b/doc/source/projectconf.rst
@@ -63,11 +63,15 @@ to support a new feature.
 
 .. note::
 
-   :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>`
+   External :mod:`Element <buildstream.element>` and :mod:`Source <buildstream.source>`
    plugins also implement their own YAML configuration fragments and as
    such are revisioned separately from the core format. See :ref:`project_plugins`
    for details on specifying a minimum version of a specific plugin.
 
+   Core :mod:`Elements <buildstream.element>` and :mod:`Sources <buildstream.source>`
+   which are maintained and distributed as a part of BuildStream are revisioned
+   under the same global ``format-version`` described here.
+
 
 Element Path
 ~~~~~~~~~~~~
@@ -195,34 +199,11 @@ External Plugins
 ----------------
 If your project makes use of any custom :mod:`Element <buildstream.element>` or
 :mod:`Source <buildstream.source>` plugins, then the project must inform BuildStream
-of the plugins it means to make use of and the origin from which it can be loaded.
+of the plugins it means to make use of and the origin from which they can be loaded.
 
 Note that plugins with the same name from different origins are not permitted.
 
 
-Core plugins
-~~~~~~~~~~~~
-Plugins provided by the BuildStream core need not be explicitly specified
-here, but you may use this section to specify a minimal format version
-to ensure that they provide the features which your project requires.
-
-.. code:: yaml
-
-   plugins:
-   - origin: core
-
-     # We require a new feature of the `git` source plugin, and
-     # a new feature introduced in version 2 of the `patch` plugin.
-     sources:
-       git: 1
-       patch: 2
-
-     # ... And a new feature of the `script` element, added
-     # in version 2 of it's own format version.
-     elements:
-       script: 2
-
-
 Local Plugins
 ~~~~~~~~~~~~~
 Local plugins are expected to be found in a subdirectory of the actual