GNOME.org
 

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

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.

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.
* 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.
* 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?

<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
-- 
Agust?n Benito Bethencourt
Principal Consultant
Codethink Ltd
We respect your privacy.   See https://www.codethink.co.uk/privacy.html
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]