I *really* don't mean to be a bother to anyone, but I'd like to continue work on this. I feel that until I can get a better sense of how the group feels about this, I can't make much progress. Perhaps this radio silence is just because this email thread got lost in among the others.
On Fri, Feb 24, 2012 at 6:50 PM, Prescott Nasser <[email protected]>wrote: > Im not against breaking compatibility when changing the version number to > a new major 2 -> 3. Im not sure how others feel. Matching Java access > modifiers seems like the right move. > > That said, what if we mark obsolete in 3.0.3 and when we make the jump to > 4.0 wipe them out? In my head we shouldn't spend too much time cleaning up > 3.0.3 aside from bug fixes if were just going to swap it for 4.0 in the > near future. > > There has to be a break at some point, making it with a major release is > the best place to make it. > > Sent from my Windows Phone > ________________________________ > From: Christopher Currens > Sent: 2/24/2012 2:45 PM > To: [email protected] > Subject: [Lucene.Net] Official stance on API changes between major versions > > 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. >
