lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christopher Currens <currens.ch...@gmail.com>
Subject [Lucene.Net] Official stance on API changes between major versions
Date Fri, 24 Feb 2012 22:45:24 GMT
A bit of background about what I've been doing lately on the project.
 Because we've now confirmed that the .NET 3.0.3 branch is a completed port
of Java 3.0.3 version, I've been spending time trying to work on some of
the bugs and improvements that are assigned to this version.  There wasn't
any real discussion about the actual features, I just created some (based
on mailing list discussions) and assigned them to the 3.0.3 release.  The
improvements I've been working on lately are ones that have bugged me
specifically since I've started using Lucene.NET.

I've worked on https://issues.apache.org/jira/browse/LUCENENET-468 and
https://issues.apache.org/jira/browse/LUCENENET-470 so far.

LUCENENET-740 is pretty much completed, all of the classes that implemented
Closeable() now implement IDisposable, having a public void Dispose()
and/or protected virtual void Dispose(bool disposing), depending if the
class is sealed or not.  What is left to do on that issue would be to make
sure that all of the tests are a) overriding the protected dispose method
as needed and b) are actually calling Dispose or are in a using statement.

I've done quite a bit of work on LUCENENET-468, as well, though it is going
far slower than 470, because there's a lot more that needs to be done and a
bit more carefully, if I don't want to break anyone's code when they move
to 3.0.  I'm not doing them in any particular order, I'm really just
running VS2010 code analysis (Rule CA1024 only, actually) and changing the
ones suggested and ones I happen across to use Properties.  I've also spent
some time trying to wrap public fields in public properties.  However, this
one in particular has been posing some problems for me, and really brings
me to the point of this email.

Due to the way most class members are named (there's a lot of redundancy),
I'm finding it difficult to move forward with some of these refactoring
without breaking backwards compatibility or adding more things to change in
regards to LUCENE-446 and CLS compliance.  For classes that are
specifically marked internal, this of course, hasn't been a problem, I just
make the breaking change and fix it other places in the library.  This is,
of course, a problem with class that are public, including classes that
*should not* be marked public but are anyway.  It's a little off topic, but
we stray far sometimes from the access modifiers defined on the java
classes.  I've found that nearly all cases were because they were needed
for the NUnit tests.  That problem no longer exists in 3.0.3, as the Test
library can now access those types in the core assembly.  I personally feel
that whenever we find an difference in access modifiers, we change it to
match java, however, if customers are using that, well, now they can't.
 That's issue number one that I wanted to discuss with the group.

Going back to the difficulties in ".NET-ifying" the API, often times if I
want to convert a Get[name]()/Set[name]() group or individual method to a
property, the resulting property name will conflict with an already
existing public field, another method with the exact same name, or the name
of the enclosing type itself.  The latter can't easily be solved, so I'm
not fretting too much about it.  The first two are easier to solve, but not
without breaking backwards compatibility for some users.

Now, the API between 2.x and 3.x differs greatly, so some customers *may*
have to make changes anyway.  However, that's not a good rule, since most,
if not all, of the breaking changes made to Lucene.NET were first obsoleted
for a period of time, and thus they were given plenty of warning to change
their code.  Unfortunately, with these changes, we haven't given them the
same notice.  So far, I've been trying my best to make sure that all
changes that have been made, have been done in a way that won't break any
compatibility.  All of the classes that now implement Dispose() still have
a Close() method that's now obsoleted (see the PS).  For properties, I've
been keeping the Get/Set methods, moving the code to the property, and
marking them obsoleted.  I figure that this is the workflow we want, but
I'm finding it's not always possible, so I'd like to see what the group has
to say about it.  How strict will we be?


Thanks,
Christopher

P.S. So in regards to classes implementing Dispose() and backwards
compatibility.  Yes, they still have a Close() method that is obsoleted.
 However, with some classes, for me to make the change, I had to add
IDisposable to an abstract class or interface.  In some cases, it was
breaking.  If Close() before was abstract, I made the new protected void
Dispose(bool) method abstract, removed virtual from Close() and had it call
Dispose().  This is a breaking change since and class that inherited from
that class will now have multiple build errors, one for trying to override
a non-virtual member (Close()) and another for not implementing the
protected dispose method.  So, perhaps that needs to be discussed as well.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message