GNOME.org
 

Re: [BuildStream] Move Docker source plugin out of bst-external

Hi all,
Jonathan, I'll be happy to be a co-maintainer for the new repository for container plugins :) The name "bst-plugins-container" seems good to me as well. (The other obvious choice is "bst-container-plugins" but as we might need more repos like "foo", "bar" in future, "bst-plugins-foo", "bst-plugins-bar" etc should be clearer.)
Since we haven't heard any objections, I think we can at least get started by creating the new repository. I don't have the permissions to do so myself, so please can one of the admins create it?
Agustin, thanks for putting together these guidelines. They seem good to me at a high-level, please see inline replies for some of the points. 

On 11/13/18 9:22 PM, Agustín Benito Bethencourt via BuildStream-list wrote:

Hi,

On Tuesday, 13 November 2018 13:42:07 CET Jonathan Maw wrote:

On 2018-11-07 16:40, Chiara Tolentino via BuildStream-list wrote:

(Forking off the discussion in [1] as this should be two separate
conversations really)

During the last BuildStream Gathering, it was generally agreed that the
Docker
source plugin should be moved out of bst-external to a new containers
repository. While the concerns regarding how CI would be run for these
separate
plugin repositories are valid and must be addressed, bst-external
already has
the issue of having to copy-paste tests from core to be able to run
them. The
new containers repository would then be a good place to start
experimenting on
how CI would eventually work for plugin repositories.

With this change, it's expected that users of the Docker source plugin
would
then have to install the migrated plugins separately (either from PyPI
or,
as in the case of bst-external currently, by cloning the repository).
And as
this only concerns bst-external, this would not affect
buildstream/buildstream
or the upcoming v1.4 release in any way.

Please let me know your thoughts and ideas on this.

Cheers,
Chiara

[1]:
https://mail.gnome.org/archives/buildstream-list/2018-October/msg00057.html


Hi Chiara,

I am in favour of this and would like to get started. I think there are
two main topics that need to be resolved (though I can get started in
the meantime):

1. Migration strategy for users
===============================

i.e. How do we move the docker source plugin with minimal disruption for
users?

My suggestion is that we should refrain from deleting the docker source
plugin from bst-external immediately, in case there are users who track
master instead of using tagged versions. We can announce our intention
to deprecate it now, and add a warning to users that the plugin is
deprecated in favour of the docker source in the new repository, and
remove the docker source plugin from bst-external when it's next updated
in the new repository.

I would be happy to hear advice about how to do this from people with
more experience with how free software projects operate, here.

Agustin, any suggestions?


I appreciate you ask.

I hope we all agree how relevant it is to have a well defined deprecation strategy for plugins we can agree on. I would 
like us to think about what is about to happen with plugins as the first example to define such (simple) plugin 
deprecation strategy, even though this is closer to a "one shot transition". I would consider 3 aspects for 
the deprecation strategy.

1. Deprecation period
2. Deprecation process.
3. Communication.

### Transition period

Since the maintenance cycle we currently have is one release cycle (6 months approx.) as Mathieu pointed I 
would link both, the deprecation period to the BuildStream maintenance cycle for now. I would open the door 
to exceptions.


+1

Policy: any plugin author whose plugin deprecation has been approved, according to the defined process (TBD), 
will maintain the original plugin available for those using the latest BuildStream release until the 
maintenance cycle of that BuildStream version is over. Request for exceptions to this period will need to be 
justified explicitly to be evaluated during roadmap stage. The author of the new plugin will be responsible 
for the proper execution of the deprecation process, in coordination with BuildStream community.

#### Communication

We have the following places we can add information to about the deprecation:
* Gitlab repo description: former and new, when appropriate. Each repo has a description field in Gitlab. A 
deprecation would be very good to be notified there.
This seems like a good idea but I feel like this will work best only when the entire repository is getting deprecated. Since we currently have many plugins in the same repository, and not all of them are getting deprecated, I am not sure if this is applicable for the docker plugin. 


* README file for each repo, when appropriate. The fact that a plugin will be deprecated, which plugin is 
deprecating it and by when, should be part of the README file
* BuildStream in detail[1] (plugin section) on the website. A short description of the former and new plugin 
should be on the website, including the deprecation relation and the timeline, just like in the README file
Are we planning to list all plugins (including external plugins) on this page? If we are planning to make it similar to the current list of external plugins [0], then it may only have the links of the entire repositories and not individual plugins. If that's the case, then it may not be possible to list deprecations there. 


* Release related information: release announcement and release feature page[2]. The release feature page has 
a table for plugins where the information about the new and deprecated plugins should be included. The 
release announcement should also mention the availability of the new plugin and the deprecation of the former 
one.

In addition, we should add:
* Ideally, the deprecation should be announced up front, once approved, as the last stage of the roadmap 
stage.
* A specific announcement in the mailing list, sent by the author when the new plugin is merged or available.

Check below what I mean.

### Deprecation process

Assuming we have the following stages:
* roadmap definition
* development/deployment
* release
* maintenance

I haven't put enough thought on this but I would say that the process might be something like:

Roadmap

* The deprecation should be proposed and approved following the roadmap definition process.
** Include the transition plan and technical considerations for current users of the plugin to be deprecated.
* Once approved, the deprecation plan will be communicated to the wider community, as any other roadmap item 
including:
** Information on the README file of the affected repos about the deprecation.
** Information on the affected Gitlab repo descriptions about the deprecation.

Development/Deployment

* The deployment will be communicated (availability for master users) including:
** A link to the technical documentation about the plugin.
** Link to the description of the plugin published on the web (BuildStream in Detail[1] page).

Release

* The BuildStream release, including the ability to use the new plugin will include:
** Reference to the new and deprecated plugin in the release announcement > ** Descriptions, including links, of the deprecated and new plugin, 
including an explicit reference to the deprecation of the plugin.

** Move the deprecated plugin repository to the buildstream-deprecated-plugin subgroup.

Maintenance
* Identification of those issues and WP MR related with the deprecated plugin. Close them before moving 
tickets to the new milestone.

The above process might seem complex initially but we already have some of the above processes in place, so 
this only adds a couple of steps which, by the way, will not be much different from what I am working on as 
new roadmap process in that specific stage. The idea is to use the above process as a plan for now and 
validate it with these first plugins deprecation.

What do you think of the above?
I think this is a good high-level overview of all the necessary steps. Do you think we can put it somewhere where it will be easier to find these steps? Perhaps somewhere in the website, docs or in buildstream/nosoftware? 


<snip>

[1] This page has not been published yet but it will during the 1.4 release. 
https://gitlab.com/BuildStream/website/blob/master/content/pages/buildstream_in_detail.md
[2] https://buildstream.build/feature.html

Best Regards



[0]: https://docs.buildstream.build/core_plugins.html#external-plugins

Cheers,
Chandan
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]