Roman, Vitaly, You're both saying right things, and you guys bring a sore topic up again.
The thing is that Nailgun's API isn't the best one.. but we're trying to improve it step-by-step, from release to release. We have so many things to reconsider and to fix that it'd require a huge effort to make backward compatible changes and support it. So we decided ignore backward compatibility for clients for awhile and consider our API as unstable. I agree with Roman that such changes must not be made secretly, and we should at least announce about them. Moreover, every core must think about consequences before approving them. So I propose to do the following things when backward incompatible change to API is required: * Announce this change in openstack-dev ML. * Wait 1 week before approving it, so anyone can prepare. * Change author has to work with QA in order make sure they are prepared for this change. Any thoughts? Thanks, Igor On Wed, Oct 21, 2015 at 5:24 PM, Vitaly Kramskikh <vkramsk...@mirantis.com> wrote: > JFYI: (re-)start of this discussion was instigated by merge of this change > (and here is revert). > > And this is actually not the first time when we make backward incompatible > changes in our API. AFAIR, the last time it was also about the network > configuration handler. We decided not to consider our API frozen, make the > changes and break backward compatibility. So now is the time to reconsider > this. > > API backward compatibility is a must for good software, but we also need to > understand that introducing API versioning is not that easy and will > increase efforts needed to make new changes in nailgun. > > I'd go this way: > > Estimate the priority of introducing API versioning - maybe we have other > things we should invest our resources to > Estimate all the disadvantages this decision might have > Fix all the issues in the current API (like this one) > Implement API versioning support (yes, we don't have this mechanism yet, so > we can't just "bump API version" like Sergii suggested in another thread) > Consider the current API as frozen v1, so backward incompatible changes (or > maybe all the changes?) should go to v2 > > > 2015-10-21 20:25 GMT+07:00 Roman Prykhodchenko <m...@romcheg.me>: >> >> Hi folks, >> >> I’d like to touch the aspect of Fuel development process that seems to be >> as wrong as possible. That aspect is how we change the API. >> >> The issue is that in Fuel anyone can change API at any point of time >> without even warning the rest of the same component’s team. Relying on this >> kind of API is basically impossible. We constantly have problems when even >> components of Fuel stop working due to unexpected changes in the API. >> Thinking about another software that must be integrated with Fuel is hardly >> possible with the current approach. >> >> As for a grown-up project there is a strong need for Fuel in general and >> for Nailgun in particular to work on a policy for making changes to their >> APIs. Living in OpenStack ecosystem we must at least take a look how it’s >> done in its components and try to do something similar. After working with >> Nova, Keystone, Ironic and other components I would propose to start with >> the following: let’s not make any changes to the API. Instead, let’s create >> a new version of Nailgun’s API that will appear in Fuel 8.0 and make all the >> changes there. That is the thing that will instantaneously make lives of >> other components much easier, if we make it now. >> >> After doing the essential part let’s think about how we are going to live >> with that in the future. There are several APIs in Fuel, the rest of the >> email is only touching Nailgun’s REST API. I can see the things somehow like >> the following: >> >> - Introduce API documentation by embedding Swagger and Swagger UI. >> The current approach when we leave API docs for documentation team is >> not effective. Swagger generates the documentation and resolves this issue. >> - After releasing a version of Fuel, it’s API is called stable and frozen >> for any changes, unless they allign API to the documentation or >> documentation to the API. >> - All changes to a stable APIs must be backported to the stable version >> of Fuel that introduced the corresponding API. >> - In order to guarantee that a stable API is not changed, Jenkins jobs >> should make automatic checks for every new patch set >> >> Details about all the above mentioned proposals can be discussed in >> separate threads so this one will stay uncluttered. I'd like to also summon >> those OpenStack folks, who tried to resolve the same issue and ask them >> about any common solutions in the ecosystem. >> >> >> - romcheg >> >> >> >> >> >> __________________________________________________________________________ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >> > > > > -- > Vitaly Kramskikh, > Fuel UI Tech Lead, > Mirantis, Inc. > > __________________________________________________________________________ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev