Open Stack

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
<vkramskikh at 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 <me at 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-request at 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-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>