On 2014-01-17 08:52, Martin Sandve Alnæs wrote:
Hi all,
in a bitbucket issue there has been some brief discussion of
deprecation strategies, which I think is worth a thread of its own.
I'll try to summarize the issue below, then ask what level we should
aim for.
The question is this: When we need to do breaking changes in FEniCS
APIs, how do we make the transition smooth for users who have to
update their codes without too much work for the developers?
In an ideal world the old APIs could be supported forever, but that
creates too much additional work and clutters the interfaces in the
long term.
For the developer doing the change it's usually easier to just let
other code break, but if we make too many breaking changes it's a lot
of work to update user codes. In particular python codes, as there is
no way to just compile and go through the errors.
A good compromise is to keep the API from version 1.x working in
1.(x+1) but introduce a deprecation warning telling the user what to
change. Then remove the old API from version 1.(x+n), for some n>1.
For deprecated APIs we need to support longer for some reason (e.g.
book code snippets), pick a suitable n>>1.
My vote is for aiming to keep interface compatibility with deprecation
warnings together with fairly frequent releases. If the old API is
removed shortly after the release of 1.(x+1) there is no clutter to
the interfaces in the long term but it's much easier to update our
codes for new releases.
I agree largely with this and support the proposal. There are some
subtleties. There are changes that are necessary to eliminate bugs,
there are changes that if a deprecated interface is maintained will
likely introduce bugs (e.g. with the very recent changes, MPI
deadlocks), and there are very low-level changes which will affect only
a very small number of downstream developers, if any. There are some
MPI:foo interface changes in MPI::foo that I'm certain are not used
outside of DOLFIN.
We should add to the deprecation warnings when an interface will be
removed; for users and to remind developers when an interface should be
removed.
Garth
Martin
_______________________________________________
fenics mailing list
[email protected]
http://fenicsproject.org/mailman/listinfo/fenics
_______________________________________________
fenics mailing list
[email protected]
http://fenicsproject.org/mailman/listinfo/fenics
