bst-external breaking change: making docker plugin work with registries at subpaths

[Chandan Singh <chandan chandansingh net>]

Hi all,

Recently I noticed that the `docker` source plugin does not work correctly
with registries hosted at subpaths. I have create GitLab issue #9 [1] with more
details but here is a quick overview.

Problem
~~~~~~~

`docker` plugin accepts `url` as a parameter and internally tries to split it
into registry URL and image name. The logic for the splitting works correctly
only if the registry endpoint is the hostname bit of the URL. For example, it
works correctly with `https://registry.hub.docker.com` but not something like
`https://myawesomeregistry.com/this-is-the-image-path/images`.

Proposed Solution
~~~~~~~~~~~~~~~~~

One way to solve this issue would be to explicitly require users to supply
registry URL and the image name separately. This will eliminate the
ambiguity and will also allow projects to configure a default registry so that
it doesn't need to be included in each element definition.

Does this approach seem okay to people?

Breaking Change
~~~~~~~~~~~~~~~

The approach I have proposed above will mean a breaking change for the
`docker` source plugin. Which brings me to my next question - how do we want
to handle breaking changes for bst-external plugins?

I would propose bumping the version number to indicate the breaking change. We
could also introduce a NEWS/CHANGELOG file similar to buildstream/buildstream
repository and provide summary for each release.

Deprecating url
~~~~~~~~~~~~~~~

We also need to decide what happens with the old `url` attribute? Seems like
we have a few options, listed roughly in order of effort required to
maintain it:

1. Remove it straight away
2. Mark it deprecated and ignore it if provided
3. Mark it deprecated and support it until next release, the new parameters
  would take priority in case of conflict

I personally do not feel strongly about either of the choices and would be okay
with either so I'll let the project maintainers comment. (By the way, who are
the maintainers of bst-external? [2])


[1]: https://gitlab.com/BuildStream/bst-external/issues/9
[2]: https://gitlab.com/BuildStream/bst-external/issues/7


Cheers,
Chandan Singh