<div dir="ltr">Hi Sebastien,<div><br></div><div>Thanks very much for kicking off what has turned into a great thread from the humble beginnings of [1] ;)<div><br></div><div>I've attempted to summarise it to distill the essence as there is a lot of detail:</div><div><br></div><div>- There seems to be general consensus that:</div><div><br></div><div>    - 1.1.0 is better than 2.0.0.</div><div>    - 1.1.0 is also better than 1.0.1.</div><div><br></div><div>   By changing the minor number users can see it is more than a bugfix release, but we're arguably abusing the naming slightly by not bumping the major number.</div><div><br></div><div>  That seeming abuse of semver is handled by a "get out of jail free card", namely that we haven't documented the gRPC protocol and hence implicitly haven't agreed (and documented) precisely what API breakage means yet.</div><div><br></div><div>  We also need to remember to include details of the breakage in the release notes.</div><div><br></div><div>- Plan B:</div><div><br></div><div>  It's worth mentioned that another thought we had yesterday was that we could revert the breaking change [2] to allow us to release a true 1.0.1.</div><div>  That would give us breathing space to investigate the breakage more fully and find a way to avoid it happening in the future (or atleast detect and minimise).</div><div><br></div><div><br></div><div>== TODO list from this thread ==</div><div><br></div><div>I've raised a bunch of issues here and referenced some existing ones. Please dive in by commenting, emojifying, assigning to yourself (please! ;), etc:</div><div><br></div><div>- Jon plans to write up a slide deck on gRPC API evolution best practices (I'd love to see this! ;)</div><div><br></div><div>- We need to document the gRPC protocol:</div><div><br></div><div>  <a href="https://github.com/kata-containers/agent/issues/150">https://github.com/kata-containers/agent/issues/150</a></div><div><br></div><div>- We need to version the gRPC protocol:</div><div><br></div><div>  <a href="https://github.com/kata-containers/kata-containers/issues/17">https://github.com/kata-containers/kata-containers/issues/17</a></div><div>  <a href="https://github.com/kata-containers/agent/issues/272">https://github.com/kata-containers/agent/issues/272</a></div><div><br></div><div>- We need to guarantee persistent state files are consumable by newer component versions:</div><div><br></div><div>  <a href="https://github.com/kata-containers/kata-containers/issues/25">https://github.com/kata-containers/kata-containers/issues/25</a></div><div><br></div><div>- We need to update our documentation to explain that we cannot handle "live upgrade":</div><div><br></div><div>  <a href="https://github.com/kata-containers/documentation/issues/178">https://github.com/kata-containers/documentation/issues/178</a></div><div><br></div><div>- We need to update our documentation to explain that all component versions must (currently) match for correct operation:</div><div><br></div><div>  <a href="https://github.com/kata-containers/documentation/issues/177">https://github.com/kata-containers/documentation/issues/177</a></div><div><br></div><div>Cheers,</div><div><br></div><div>James</div><div><br></div><div><div>[1] - <a href="https://github.com/kata-containers/proxy/pull/76" target="_blank">https://github.com/kata-<wbr>containers/proxy/pull/76</a><br><div>[2] - <a href="https://github.com/kata-containers/runtime/pull/357" target="_blank" style="color:rgb(17,85,204);font-size:small;background-color:rgb(255,255,255)">https://github.com/kata-<wbr>containers/runtime/pull/357</a></div><div><br></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">2018-06-22 10:55 GMT+01:00 Thierry Carrez <span dir="ltr"><<a href="mailto:thierry@openstack.org" target="_blank">thierry@openstack.org</a>></span>:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><span>zhangwei (CR) wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
To summarize:<br>
1) We  already break the backward compatibility, and we will break a lot more in near future definitely.  Actually in Vancouver, the participants all agree that we can't promise the API won't be broken and current API isn't a stable version.<br>
2) Before we claim that kata can support "live ugrade" and kata is real production ready, I'm fine with the breakage and also fine with 1.0.1 or 1.1.0, maybe latter one looks better.<br>
3) After we claim that kata can support "live upgrade" in future, we should reject any modifications which will break the running workloads, unless this is really inevitable, by then, we need to upgrade kata version from x.0.0 to y.0.0.<br>
But I hope our kata developers can understand what a disaster this could be to a cloud provider like us :-(, and I hope this will never happen.<br>
4) Better document that we don't support "live upgrade" yet, and tell users that if you want to upgrade to this new kata-containers version, you must stop all you running kata containers, or there will be anticipated issues.<br>
</blockquote>
<br></span>
That summary sounds in line with what Jon said... the protocol between the runtime and the agent is not (yet) part of the external contract for Kata. Once it is (be it by supporting live upgrade or other explicit documentation that you support mixing versions between agent and runtime) then you should avoid breaking that altogether (and bump X number in the case you really need to).<br>
<br>
In example 1 from Sebastien (PauseContainer()), I would still recommend you bump Y though, and make it 1.1.0. You're adding a feature and modifying the protocol. I would keep .Z bumps for basic bugfixes that do not introduce incompatible protocol changes at all, if only to develop user confidence that those .Z bumps can be deployed with limited risk.<span class="gmail-m_-1050332158723852138HOEnZb"><font color="#888888"><br>
<br>
-- <br>
Thierry Carrez (ttx)</font></span><div class="gmail-m_-1050332158723852138HOEnZb"><div class="gmail-m_-1050332158723852138h5"><br>
<br>
______________________________<wbr>_________________<br>
kata-dev mailing list<br>
<a href="mailto:kata-dev@lists.katacontainers.io" target="_blank">kata-dev@lists.katacontainers.<wbr>io</a><br>
<a href="http://lists.katacontainers.io/cgi-bin/mailman/listinfo/kata-dev" rel="noreferrer" target="_blank">http://lists.katacontainers.io<wbr>/cgi-bin/mailman/listinfo/kata<wbr>-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail-m_-1050332158723852138gmail_signature"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><font color="#888888"><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace">James<br>---</span></span></font></div><div dir="ltr"><a href="https://katacontainers.io/" style="color:rgb(17,85,204);font-family:monospace,monospace" target="_blank">https://katacontainers.io/</a><span style="color:rgb(136,136,136);font-family:monospace,monospace"> | <a href="https://github.com/clearcontainers" target="_blank">https://github.com/kata-<wbr>containers</a></span><font color="#888888"><span style="font-family:monospace,monospace"><span style="font-family:monospace,monospace"><br></span></span></font></div><div dir="ltr"><font color="#888888"><font face="monospace, monospace">Open Source Technology Center</font><br><font face="monospace, monospace">Intel Corporation (UK) Ltd. - Co. Reg. #1134945 - Pipers Way, Swindon SN3 1RJ.</font></font><br></div></div></div></div></div></div></div></div></div></div></div>
</div></div></div>